Merge "Update documentation regarding Ceilometer API V2"

doc/source/deploy/configuration.rst

@@ -284,20 +284,34 @@ Please check your hypervisor configuration to correctly handle
 
 .. _`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'
+                                  )
+