Update documentation regarding Ceilometer API V2

Today, the watcher Decision Engine is not relying on Ceilometer V2 API
to query the metrics necessary for the optimization algorithm.
This patchset update the documentation to use Ceilometer API with
watcher

Change-Id: I62cf0ea7b1766b00601f3dcbbbfe20b4a9567570

doc/source/deploy/configuration.rst

@@ -281,20 +281,34 @@ Please check your hypervisor configuration to correctly handle `instance migrati
 
 .. _`instance migration`: http://docs.openstack.org/admin-guide-cloud/compute-configuring-migrations.html
 
-Configure Ceilometer
-====================
+Configure Measurements
+======================
 
-The default strategy 'basic_consolidation' provided by watcher requires
-Ceilometer to collect the "compute.node.cpu.*." and "cpu_util" measurements
+You can configure and install Ceilometer by following the documentation below :
 
-#. Add/Update the following lines into the /etc/nova/nova.conf configuration file:
+#. http://docs.openstack.org/developer/ceilometer
+#. http://docs.openstack.org/kilo/install-guide/install/apt/content/ceilometer-nova.html
 
+The built-in strategy 'basic_consolidation' provided by watcher requires
+"**compute.node.cpu.percent**" and "**cpu_util**" measurements to be collected
+by Ceilometer.
+The measurements available depend on the hypervisors that OpenStack manages on
+the specific implementation.
+You can find the measurements available per hypervisor and OpenStack release on
+the OpenStack site.
+You can use 'ceilometer meter-list' to list the available meters.
 
-    .. code-block:: bash
+For more information:
+http://docs.openstack.org/developer/ceilometer/measurements.html
 
-      $ compute_available_monitors=nova.compute.monitors.all_monitors
-      $ compute_monitors=ComputeDriverCPUMonitor
+Ceilometer is designed to collect measurements from OpenStack services and from
+other external components. If you would like to add new meters to the currently
+existing ones, you need to follow the documentation below:
 
-#. Restart the Nova compute service and the Nova scheduler after completing the above configuration.
+#. http://docs.openstack.org/developer/ceilometer/new_meters.html
 
-#. For more information: `Integrating your metrics plug-in with Nova <http://www-01.ibm.com/support/knowledgecenter/SS8MU9_2.2.0/Admin/tasks/integratingplugin.dita>`_
+The Ceilometer collector uses a pluggable storage system, meaning that you can
+pick any database system you prefer.
+The original implementation has been based on MongoDB but you can create your
+own storage driver using whatever technology you want.
+For more information : https://wiki.openstack.org/wiki/Gnocchi

doc/source/dev/plugins.rst

@@ -119,3 +119,65 @@ there are no guarantees that utilizing them as is will be supported, as
 they may require a set of metrics which is not yet available within the
 Telemetry service. In such a case, please do make sure that you first
 check/configure the latter so your new strategy can be fully functional.
+
+Querying metrics
+~~~~~~~~~~~~~~~~
+
+The metrics available depend on the hypervisors that OpenStack manages on
+the specific implementation. You can find the metrics available per hypervisor
+and OpenStack release on the OpenStack site.
+
+There are different possible ways to obtain usage metrics in Watcher, you can
+use the default Ceilometer API or our Helper.
+The Helper attempted to make the Ceilometer API more reusable and easy to use.
+
+Read usage metrics using the Python binding
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can find the information about the Ceilometer Python binding on the
+OpenStack `ceilometer client python API documentation
+<http://docs.openstack.org/developer/python-ceilometerclient/api.html>`_
+
+The first step is to authenticate against the Ceilometer service
+(assuming that you already imported the Ceilometer client for Python)
+with this call:
+
+.. code-block:: py
+
+ cclient = ceilometerclient.client.get_client(VERSION, os_username=USERNAME,
+  os_password=PASSWORD, os_tenant_name=PROJECT_NAME, os_auth_url=AUTH_URL)
+
+Using that you can now query the values for that specific metric:
+
+.. code-block:: py
+
+ value_cpu = cclient.samples.list(meter_name='cpu_util', limit=10, q=query)
+
+Read usage metrics using the Watcher Cluster History Helper
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here below is the abstract ``BaseClusterHistory`` class of the Helper.
+
+.. automodule:: watcher.metrics_engine.cluster_history.api
+    :noindex:
+
+.. autoclass:: BaseClusterHistory
+    :members:
+
+
+The following snippet code shows how to create a Cluster History class:
+
+.. code-block:: py
+
+    query_history  = CeilometerClusterHistory()
+
+Using that you can now query the values for that specific metric:
+
+.. code-block:: py
+
+    query_history.statistic_aggregation(resource_id=hypervisor.uuid,
+                                  meter_name='compute.node.cpu.percent',
+                                  period="7200",
+                                  aggregate='avg'
+                                  )
+