From 6979b16e2c5ce84fb04cbb8ea34a55ea77a8abe7 Mon Sep 17 00:00:00 2001
From: Phil Neal <phil.neal@hp.com>
Date: Mon, 29 Apr 2013 12:06:15 -0600
Subject: [PATCH] Adds examples of CLI and API queries to the V2 documentation.

This patch includes additional reST-formatted text that will add new/expanded examples of v2 API use to the existing documentation.
Fixes: bug #1160929

Change-Id: I63fa9dd8b050a63f005c4a5b35399355fdeb7605
---
 doc/source/webapi/v2.rst | 51 +++++++++++++++++++++++++++++++++++++---
 1 file changed, 48 insertions(+), 3 deletions(-)

diff --git a/doc/source/webapi/v2.rst b/doc/source/webapi/v2.rst
index 6c0363bf4..30f7abd65 100644
--- a/doc/source/webapi/v2.rst
+++ b/doc/source/webapi/v2.rst
@@ -41,10 +41,55 @@ should be a list of Query data structures:
 .. autotype:: ceilometer.api.controllers.v2.Query
    :members:
 
-For example, to list all samples since a specified time::
 
-    $ curl -X GET -H 'X-Auth-Token:token_id' -H 'Content-Type:application/json' -d '{"q":[{"field": "timestamp","op": "ge","value":"2013-04-01T13:34:17"}]}' http://localhost:8777/v2/meters
+API and CLI query examples
+==========================
+
+
+CLI Queries
++++++++++++
+Ceilometer CLI Commands::
+
+     $ ceilometer --debug --os-username <username_here> --os-password <password_here> --os-auth-url http://localhost:5000/v2.0/ --os-tenant-name admin  meter-list
 
 or::
 
-    $ curl -X GET -H 'X-Auth-Token:token_id' "http://localhost:8777/v2/meters?q.field=timestamp&q.op=ge&q.value=2013-04-01T13:34:17"
+     $ ceilometer --os-username admin --os-password password --os-tenant-name admin project-list
+
+
+.. note:: The *username*, *password*, and *tenant-name* options are required to be present in these commands or specified via environment variables. Note that the in-line commands will override the environment variables.
+
+
+API Queries
++++++++++++
+Ceilometer API calls:
+
+.. note:: To successfully query the Ceilometer you must first get a project-specific token from the Keystone service and add it to any API calls that you execute against that project. See the `Openstack credentials documentation <http://docs.openstack.org/api/quick-start/content/index.html#getting-credentials-a00665>`_ for additional details.
+
+A simple query to return a list of available meters::
+
+     $ curl -X GET -H 'X-Auth-Token:<inserttokenhere>' "http://localhost:8777/v2/meters"
+
+A query to return the list of resources::
+
+     $ curl -X GET -H 'X-Auth-Token:<inserttokenhere>' "http://localhost:8777/v2/resources"
+
+A query to return the list of meters, limited to a specific meter type::
+
+     $ curl -X GET -H 'X-Auth-Token:<inserttokenhere>' "http://localhost:8777/v2/meters/disk.root.size"
+
+A query using filters (see: `query filter section <http://docs.openstack.org/developer/ceilometer/webapi/v2.html#filtering-queries>`_)::
+
+     $ curl -X GET -H 'X-Auth-Token:<inserttokenhere>' "http://localhost:8777/v2/meters/instance?q.field=metadata.event_type&q.value=compute.instance.delete.start"
+
+Additional examples::
+
+     $ curl -X GET -H 'X-Auth-Token:<inserttokenhere>' "http://localhost:8777/v2/meters/disk.root.size?q.field=resource_id&q.op=eq&q.value=<resource_id_here>"
+
+or::
+
+     $ curl -X GET -H 'X-Auth-Token:<inserttokenhere>' "http://localhost:8777/v2/meters/instance?q.field=metadata.event_type&q.value=compute.instance.exists"
+
+and finally, a JSON-based example::
+
+     $ curl -X GET -H 'X-Auth-Token:<inserttokenhere>' -H 'Content-Type:application/json' -d '{"q":[{"field": "timestamp","op": "ge","value":"2013-04-01T13:34:17"}]}' http://localhost:8777/v2/meters