9a14370266
Thanks to sphinxcontrib-docbookrestapi, the documentation for the REST API can be automatically generated. Add a target to do this. Change-Id: I9dda41bc00160bf1be1e275d9ac94a3a53571688
412 lines
15 KiB
ReStructuredText
412 lines
15 KiB
ReStructuredText
.. 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.<field>*. 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.<field>* does not match its value, and when
|
|
*<field>* 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 <username_here> --os-password <password_here> --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 <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 -H 'X-Auth-Token: <inserttokenhere>' \
|
|
"http://localhost:8777/v2/meters"
|
|
|
|
A query to return the list of resources::
|
|
|
|
curl -H 'X-Auth-Token: <inserttokenhere>' \
|
|
"http://localhost:8777/v2/resources"
|
|
|
|
A query to return the list of samples, limited to a specific meter type::
|
|
|
|
curl -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 -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 -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 -H 'X-Auth-Token: <inserttokenhere>' \
|
|
"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: <inserttokenhere>' \
|
|
"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: <inserttokenhere>' -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: <inserttokenhere>' -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: <inserttokenhere>' -H 'Content-Type: application/json' \
|
|
-d '<insertyoursampleslisthere>' \
|
|
http://localhost:8777/v2/meters/<insertyourmeternamehere>
|
|
|
|
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.
|