.. docbookrestapi ============ V2 Web API ============ Resources ========= .. rest-controller:: ceilometer.api.controllers.v2:ResourcesController :webprefix: /v2/resources .. autotype:: ceilometer.api.controllers.v2.Resource :members: Meters ====== .. rest-controller:: ceilometer.api.controllers.v2:MetersController :webprefix: /v2/meters .. rest-controller:: ceilometer.api.controllers.v2:MeterController :webprefix: /v2/meters Samples and Statistics ====================== .. autotype:: ceilometer.api.controllers.v2.Meter :members: .. autotype:: ceilometer.api.controllers.v2.Sample :members: .. autotype:: ceilometer.api.controllers.v2.Statistics :members: .. _alarms-api: Alarms ====== .. rest-controller:: ceilometer.api.controllers.v2:AlarmsController :webprefix: /v2/alarms .. rest-controller:: ceilometer.api.controllers.v2:AlarmController :webprefix: /v2/alarms .. autotype:: ceilometer.api.controllers.v2.Alarm :members: .. autotype:: ceilometer.api.controllers.v2.AlarmThresholdRule :members: .. autotype:: ceilometer.api.controllers.v2.AlarmCombinationRule :members: Filtering Queries ================= Many of the endpoints above accept a query filter argument, which should be a list of Query data structures. Whatever the endpoint you want to apply a filter on, you always filter on the fields of the *Sample* type (for example, if you apply a filter on a query for statistics, you won't target *duration_start* field of *Statistics*, but *timestamp* field of *Sample*). You may also apply filters based on the values of one or more of the *resource_metadata* field, in which case you should target *metadata.*. Notice, 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. In other words, the API call will return HTTP 200 in both scenarios: when a query with *metadata.* does not match its value, and when ** itself does not exist in any of the records being queried. .. autotype:: ceilometer.api.controllers.v2.Query :members: Links ===== .. autotype:: ceilometer.api.controllers.v2.Link :members: API and CLI query examples ========================== CLI Queries +++++++++++ Ceilometer CLI Commands:: $ ceilometer --debug --os-username --os-password --os-auth-url http://localhost:5000/v2.0/ --os-tenant-name admin meter-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 `_ for additional details. A simple query to return a list of available meters:: curl -H 'X-Auth-Token: ' \ "http://localhost:8777/v2/meters" A query to return the list of resources:: curl -H 'X-Auth-Token: ' \ "http://localhost:8777/v2/resources" A query to return the list of samples, limited to a specific meter type:: curl -H 'X-Auth-Token: ' \ "http://localhost:8777/v2/meters/disk.root.size" A query using filters (see: `query filter section `_):: curl -H 'X-Auth-Token: ' \ "http://localhost:8777/v2/meters/instance?q.field=metadata.event_type&q.value=compute.instance.delete.start" Additional examples:: curl -H 'X-Auth-Token: ' \ "http://localhost:8777/v2/meters/disk.root.size?q.field=resource_id&q.op=eq&q.value=" or:: curl -H 'X-Auth-Token: ' \ "http://localhost:8777/v2/meters/instance?q.field=metadata.event_type&q.value=compute.instance.exists" You can specify multiple filters by using an array of queries (order matters):: curl -H 'X-Auth-Token: ' \ "http://localhost:8777/v2/meters/instance"\ "?q.field=metadata.event_type&q.value=compute.instance.exists"\ "&q.field=timestamp&q.op=gt&q.value=2013-07-03T13:34:17" JSON based example:: curl -H 'X-Auth-Token: ' -H 'Content-Type: application/json' \ -d '{"q":[{"field": "timestamp","op": "ge","value":"2013-04-01T13:34:17"}]}' \ http://localhost:8777/v2/meters JSON based example with multiple filters:: curl -H 'X-Auth-Token: ' -H 'Content-Type: application/json' \ -d '{"q":[{"field": "timestamp","op": "ge","value":"2013-04-01T13:34:17"},'\ "'{"field": "project_id","op": "eq","value":"8d6057bc-5b90-4296-afe0-84acaa2ef909"}]}' \ http://localhost:8777/v2/meters/instance Functional examples +++++++++++++++++++ The examples below are meant to help you understand how to query the Ceilometer API to build custom metrics report. The query parameters should be encoded using one of the above methods, e.g. as the URL parameters or as JSON encoded data passed to the GET request. Get the list of samples about instances running for June 2013:: GET /v2/meters/instance q: [{"field": "timestamp", "op": "ge", "value": "2013-06-01T00:00:00"}, {"field": "timestamp", "op": "lt", "value": "2013-07-01T00:00:00"}] Get the list of samples about instances running for June 2013 for a particular project:: GET /v2/meters/instance q: [{"field": "timestamp", "op": "ge", "value": "2013-06-01T00:00:00"}, {"field": "timestamp", "op": "lt", "value": "2013-07-01T00:00:00"}, {"field": "project_id", "op": "eq", "value": "8d6057bc-5b90-4296-afe0-84acaa2ef909"}] Get the list of samples about instances with *m1.tiny* flavor running for June 2013 for a particular project:: GET /v2/meters/instance:m1.tiny q: [{"field": "timestamp", "op": "ge", "value": "2013-06-01T00:00:00"}, {"field": "timestamp", "op": "lt", "value": "2013-07-01T00:00:00"}, {"field": "project_id", "op": "eq", "value": "8d6057bc-5b90-4296-afe0-84acaa2ef909"}] Now you may want to have statistics on the meters you are targeting. Consider the following example where you are getting the list of samples about CPU utilisation of a given instance (identified by its *resource_id*) running for June 2013:: GET /v2/meters/cpu_util q: [{"field": "timestamp", "op": "ge", "value": "2013-06-01T00:00:00"}, {"field": "timestamp", "op": "lt", "value": "2013-07-01T00:00:00"}, {"field": "resource_id", "op": "eq", "value": "64da755c-9120-4236-bee1-54acafe24980"}] You can have statistics on the list of samples requested (*avg*, *sum*, *max*, *min*, *count*) computed on the full duration:: GET /v2/meters/cpu_util/statistics q: [{"field": "timestamp", "op": "ge", "value": "2013-06-01T00:00:00"}, {"field": "timestamp", "op": "lt", "value": "2013-07-01T00:00:00"}, {"field": "resource_id", "op": "eq", "value": "64da755c-9120-4236-bee1-54acafe24980"}] You may want to aggregate samples over a given period (10 minutes for example) in order to get an array of the statistics computed on smaller durations:: GET /v2/meters/cpu_util/statistics q: [{"field": "timestamp", "op": "ge", "value": "2013-06-01T00:00:00"}, {"field": "timestamp", "op": "lt", "value": "2013-07-01T00:00:00"}, {"field": "resource_id", "op": "eq", "value": "64da755c-9120-4236-bee1-54acafe24980"}] period: 600 The *period* parameter aggregates by time range. You can also aggregate by field using the *groupby* parameter. Currently, the *user_id*, *resource_id*, *project_id*, and *source* fields are supported. Below is an example that uses a query filter and group by aggregation on *project_id* and *resource_id*:: GET /v2/meters/instance/statistics q: [{"field": "user_id", "op": "eq", "value": "user-2"}, {"field": "source", "op": "eq", "value": "source-1"}] groupby: ["project_id", "resource_id"] The statistics will be returned in a list, and each entry of the list will be labeled with the group name. For the previous example, the first entry might have *project_id* be "project-1" and *resource_id* be "resource-1", the second entry have *project_id* be "project-1" and *resource_id* be "resource-2", and so on. You can request both period and group by aggregation in the same query:: GET /v2/meters/instance/statistics q: [{"field": "source", "op": "eq", "value": "source-1"}] groupby: ["project_id"] period: 7200 Note that period aggregation is applied first, followed by group by aggregation. Order matters because the period aggregation determines the time ranges for the statistics. Below is a real-life query:: GET /v2/meters/image/statistics groupby: ["project_id", "resource_id"] With the return values:: [{"count": 4, "duration_start": "2013-09-18T19:08:33", "min": 1.0, "max": 1.0, "duration_end": "2013-09-18T19:27:30", "period": 0, "sum": 4.0, "period_end": "2013-09-18T19:27:30", "duration": 1137.0, "period_start": "2013-09-18T19:08:33", "avg": 1.0, "groupby": {"project_id": "c2334f175d8b4cb8b1db49d83cecde78", "resource_id": "551f495f-7f49-4624-a34c-c422f2c5f90b"}, "unit": "image"}, {"count": 4, "duration_start": "2013-09-18T19:08:36", "min": 1.0, "max": 1.0, "duration_end": "2013-09-18T19:27:30", "period": 0, "sum": 4.0, "period_end": "2013-09-18T19:27:30", "duration": 1134.0, "period_start": "2013-09-18T19:08:36", "avg": 1.0, "groupby": {"project_id": "c2334f175d8b4cb8b1db49d83cecde78", "resource_id": "7c1157ed-cf30-48af-a868-6c7c3ad7b531"}, "unit": "image"}, {"count": 4, "duration_start": "2013-09-18T19:08:34", "min": 1.0, "max": 1.0, "duration_end": "2013-09-18T19:27:30", "period": 0, "sum": 4.0, "period_end": "2013-09-18T19:27:30", "duration": 1136.0, "period_start": "2013-09-18T19:08:34", "avg": 1.0, "groupby": {"project_id": "c2334f175d8b4cb8b1db49d83cecde78", "resource_id": "eaed9cf4-fc99-4115-93ae-4a5c37a1a7d7"}, "unit": "image"}] If you want to retrieve all the instances (not the list of samples, but the resource itself) that have been run during this month for a given project, you should ask the resource endpoint for the list of resources (all types: including storage, images, networking, ...):: GET /v2/resources q: [{"field": "timestamp", "op": "ge", "value": "2013-06-01T00:00:00"}, {"field": "timestamp", "op": "lt", "value": "2013-07-01T00:00:00"}, {"field": "project_id", "op": "eq", "value": "8d6057bc-5b90-4296-afe0-84acaa2ef909"}] Then look for resources that have an *instance* meter linked to them. That will indicate resources that have been measured as being instance. You can then request their samples to have more detailed information, like their state or their flavor:: GET /v2/meter/instance q: [{"field": "timestamp", "op": "ge", "value": "2013-06-01T00:00:00"}, {"field": "timestamp", "op": "lt", "value": "2013-07-01T00:00:00"}, {"field": "resource_id", "op": "eq", "value": "64da755c-9120-4236-bee1-54acafe24980"}, {"field": "project_id", "op": "eq", "value": "8d6057bc-5b90-4296-afe0-84acaa2ef909"}] This will return a list of samples that have been recorded on this particular resource. You can inspect them to retrieve information, such as the instance state (check the *metadata.vm_state* field) or the instance flavor (check the *metadata.flavor* field). You can request nested metadata fields by using a dot to delimit the fields (e.g. *metadata.weighted_host.host* for *instance.scheduled* meter) To retrieve only the 3 last samples of a meters, you can pass the *limit* parameter to the query:: GET /v2/meter/instance q: [{"field": "timestamp", "op": "ge", "value": "2013-06-01T00:00:00"}, {"field": "timestamp", "op": "lt", "value": "2013-07-01T00:00:00"}, {"field": "resource_id", "op": "eq", "value": "64da755c-9120-4236-bee1-54acafe24980"}, {"field": "project_id", "op": "eq", "value": "8d6057bc-5b90-4296-afe0-84acaa2ef909"}] limit: 3 This query would only return the last 3 samples. .. _user-defined-data: User-defined data +++++++++++++++++ It is possible to add your own samples (created from data retrieved in any way like monitoring agents on your instances) in Ceilometer to store them and query on them. You can even get *Statistics* on your own inserted data. By adding a *Sample* to a *Resource*, you create automatically the corresponding *Meter* if it does not exist already. To achieve this, you have to POST a list of one to many samples in JSON format:: curl -X POST -H 'X-Auth-Token: ' -H 'Content-Type: application/json' \ -d '' \ http://localhost:8777/v2/meters/ Fields *source*, *timestamp*, *project_id* and *user_id* are automatically added if not present in the samples. Field *message_id* is not taken into account if present and an internal value will be set. Here is an example showing how to add a sample for a *ram_util* meter (already existing or not):: POST /v2/meters/ram_util body: [ { "counter_name": "ram_util", "user_id": "4790fbafad2e44dab37b1d7bfc36299b", "resource_id": "87acaca4-ae45-43ae-ac91-846d8d96a89b", "resource_metadata": { "display_name": "my_instance", "my_custom_metadata_1": "value1", "my_custom_metadata_2": "value2" }, "counter_unit": "%", "counter_volume": 8.57762938230384, "project_id": "97f9a6aaa9d842fcab73797d3abb2f53", "counter_type": "gauge" } ] You get back the same list containing your example completed with the missing fields : *source* and *timestamp* in this case.