~ubuntu-branches/ubuntu/vivid/ceilometer/vivid

.. autotype:: ceilometer.api.controllers.v2.Meter

   :members:

 

.. autotype:: ceilometer.api.controllers.v2.OldSample

   :members:

 

.. autotype:: ceilometer.api.controllers.v2.AlarmTimeConstraint

   :members:

 

Ceilometer's REST API currently supports two types of queries. The Simple

Query functionality provides simple filtering on several fields of the

*Sample* type. Complex Query provides the possibility to specify queries

with logical and comparison operators on the fields of *Sample*.

 

You may also apply filters based on the values of one or more of the

*resource_metadata* field, which you can identify by using *metadata.<field>*

syntax in either type of query. Note, however, that given the free-form

nature of *resource_metadata* field, there is no practical or consistent way

to validate the query fields under *metadata* domain like it is done for

all other fields.

 

.. note:: The API call will return HTTP 200 OK status for both of the

   following cases: when a query with *metadata.<field>* does not match its

   value, and when *<field>* itself does not exist in any of the records being

   queried.

 

Simple Query

++++++++++++

field of *Sample*).

Complex Query

+++++++++++++

The filter expressions of the Complex Query feature operate on the fields

of *Sample*, *Alarm* and *AlarmChange*. The following comparison operators are

supported: *=*, *!=*, *<*, *<=*, *>*, *>=* and *in*; and the following logical

operators can be used: *and* *or* and *not*. The field names are validated

against the database models.

 

.. note:: The *not* operator has different meaning in Mongo DB and in SQL DB engine.

   If the *not* operator is applied on a non existent metadata field then

   the result depends on the DB engine. For example if

   {"not": {"metadata.nonexistent_field" : "some value"}} filter is used in a query

   the Mongo DB will return every Sample object as *not* operator evaluated true

   for every Sample where the given field does not exists. See more in the Mongod DB doc.

   In the other hand SQL based DB engine will return empty result as the join operation

   on the metadata table will return zero row as the on clause of the join which

   tries to match on the metadata field name is never fulfilled.

 

Complex Query supports defining the list of orderby expressions in the form

of [{"field_name": "asc"}, {"field_name2": "desc"}, ...].

 

The number of the returned items can be bounded using the *limit* option.

 

The *filter*, *orderby* and *limit* are all optional fields in a query.

 

.. rest-controller:: ceilometer.api.controllers.v2:QuerySamplesController

   :webprefix: /v2/query/samples

 

.. rest-controller:: ceilometer.api.controllers.v2:QueryAlarmsController

   :webprefix: /v2/query/alarms

 

.. rest-controller:: ceilometer.api.controllers.v2:QueryAlarmHistoryController

   :webprefix: /v2/query/alarms/history

 

.. autotype:: ceilometer.api.controllers.v2.ComplexQuery

   :members:

 

.. 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.

Functional example for Complex Query

++++++++++++++++++++++++++++++++++++

 

This example demonstrates how complex query filter expressions can be generated and sent

to the /v2/query/samples endpoint of Ceilometer API using POST request.

 

To check for *cpu_util* samples reported between 18:00-18:15 or between 18:30 - 18:45

on a particular date (2013-12-01), where the utilization is between 23 and 26 percent,

but not exactly 25.12 percent, the following filter expression can be created::

 

    {"and":

     [{"and":

      [{"=": {"counter_name": "cpu_util"}},

       {">": {"counter_volume": 0.23}},

       {"<": {"counter_volume": 0.26}},

       {"not": {"=": {"counter_volume": 0.2512}}}]},

      {"or":

       [{"and":

        [{">": {"timestamp": "2013-12-01T18:00:00"}},

         {"<": {"timestamp": "2013-12-01T18:15:00"}}]},

        {"and":

         [{">": {"timestamp": "2013-12-01T18:30:00"}},

          {"<": {"timestamp": "2013-12-01T18:45:00"}}]}]}]}

 

Different sorting criteria can be defined for the query filter, for example the results

can be ordered in an ascending order by the *counter_volume* and descending order based on

the *timestamp*. The following order by expression has to be created for specifying this

criteria::

 

    [{"counter_volume": "ASC"}, {"timestamp": "DESC"}]

 

As the current implementation accepts only string values as query filter and order by

definitions, the above defined expressions have to be converted to string values.

By adding a limit criteria to the request, which maximizes the number of returned samples

to four, the query looks like the following::

 

    {

    "filter" : "{\"and\":[{\"and\": [{\"=\": {\"counter_name\": \"cpu_util\"}}, {\">\": {\"counter_volume\": 0.23}}, {\"<\": {\"counter_volume\": 0.26}}, {\"not\": {\"=\": {\"counter_volume\": 0.2512}}}]}, {\"or\": [{\"and\": [{\">\": {\"timestamp\": \"2013-12-01T18:00:00\"}}, {\"<\": {\"timestamp\": \"2013-12-01T18:15:00\"}}]}, {\"and\": [{\">\": {\"timestamp\": \"2013-12-01T18:30:00\"}}, {\"<\": {\"timestamp\": \"2013-12-01T18:45:00\"}}]}]}]}",

    "orderby" : "[{\"counter_volume\": \"ASC\"}, {\"timestamp\": \"DESC\"}]",

    "limit" : 4

    }

 

A query request looks like the following with curl::

 

    curl -X POST -H 'X-Auth-Token: <inserttokenhere>' -H 'Content-Type: application/json' \

      -d '<insertyourqueryexpressionhere>' \

       http://localhost:8777/v2/query/samples