5004d5486d
This change add the minimal documentation about alarming DocImpact Change-Id: Id1be0c69cef787753913af99794e295d453674f5
334 lines
11 KiB
ReStructuredText
334 lines
11 KiB
ReStructuredText
============
|
|
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
|
|
======
|
|
|
|
.. rest-controller:: ceilometer.api.controllers.v2:AlarmsController
|
|
:webprefix: /v2/alarms
|
|
|
|
.. autotype:: ceilometer.api.controllers.v2.Alarm
|
|
: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*):
|
|
|
|
.. 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
|
|
|
|
or::
|
|
|
|
$ ceilometer --os-username admin --os-password password --os-tenant-name admin project-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 meters, 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
|
|
|
|
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
|
|
+++++++++++++++++
|
|
|
|
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.
|