V2 Web API

Resources

type Resource

An externally defined object for which samples have been received.

Data samples:

Json
{
    "links": [
        {
            "href": "http://localhost:8777/v2/resources/bd9431c1-8d69-4ad3-803a-8d4a6b89fd36",
            "rel": "self"
        },
        {
            "href": "http://localhost:8777/v2/meters/volume?q.field=resource_id&q.value=bd9431c1-8d69-4ad3-803a-8d4a6b89fd36",
            "rel": "volume"
        }
    ],
    "metadata": {
        "name1": "value1",
        "name2": "value2"
    },
    "project_id": "35b17138-b364-4e6a-a131-8f3099c5be68",
    "resource_id": "bd9431c1-8d69-4ad3-803a-8d4a6b89fd36",
    "user_id": "efd87807-12d2-4b38-9c70-5f5c2ac427ff"
}
XML
<value>
  <links>
    <item>
      <href>http://localhost:8777/v2/resources/bd9431c1-8d69-4ad3-803a-8d4a6b89fd36</href>
      <rel>self</rel>
    </item>
    <item>
      <href>http://localhost:8777/v2/meters/volume?q.field=resource_id&amp;q.value=bd9431c1-8d69-4ad3-803a-8d4a6b89fd36</href>
      <rel>volume</rel>
    </item>
  </links>
  <metadata>
    <item>
      <key>name2</key>
      <value>value2</value>
    </item>
    <item>
      <key>name1</key>
      <value>value1</value>
    </item>
  </metadata>
  <project_id>35b17138-b364-4e6a-a131-8f3099c5be68</project_id>
  <resource_id>bd9431c1-8d69-4ad3-803a-8d4a6b89fd36</resource_id>
  <user_id>efd87807-12d2-4b38-9c70-5f5c2ac427ff</user_id>
</value>
first_sample_timestamp
Type:datetime

UTC date & time of the first sample associated with the resource

last_sample_timestamp
Type:datetime

UTC date & time of the last sample associated with the resource

Type:list(Link)

A list containing a self link and associated meter links

metadata
Type:dict(unicode: unicode)

Arbitrary metadata associated with the resource

project_id
Type:unicode

The ID of the owning project or tenant

resource_id
Type:unicode

The unique identifier for the resource

user_id
Type:unicode

The ID of the user who created the resource or updated it last

Meters

Samples and Statistics

type Meter

One category of measurements.

Data samples:

Json
{
    "meter_id": "YmQ5NDMxYzEtOGQ2OS00YWQzLTgwM2EtOGQ0YTZiODlmZDM2K2luc3RhbmNl\n",
    "name": "instance",
    "project_id": "35b17138-b364-4e6a-a131-8f3099c5be68",
    "resource_id": "bd9431c1-8d69-4ad3-803a-8d4a6b89fd36",
    "source": "openstack",
    "type": "gauge",
    "unit": "instance",
    "user_id": "efd87807-12d2-4b38-9c70-5f5c2ac427ff"
}
XML
<value>
  <meter_id>YmQ5NDMxYzEtOGQ2OS00YWQzLTgwM2EtOGQ0YTZiODlmZDM2K2luc3RhbmNl
</meter_id>
  <name>instance</name>
  <project_id>35b17138-b364-4e6a-a131-8f3099c5be68</project_id>
  <resource_id>bd9431c1-8d69-4ad3-803a-8d4a6b89fd36</resource_id>
  <source>openstack</source>
  <type>gauge</type>
  <unit>instance</unit>
  <user_id>efd87807-12d2-4b38-9c70-5f5c2ac427ff</user_id>
</value>
meter_id
Type:unicode

The unique identifier for the meter

name
Type:unicode

The unique name for the meter

project_id
Type:unicode

The ID of the project or tenant that owns the resource

resource_id
Type:unicode

The ID of the Resource for which the measurements are taken

source
Type:unicode

The ID of the source that identifies where the meter comes from

type
Type:Enum(gauge, delta, cumulative)

The meter type (see Measurements)

unit
Type:unicode

The unit of measure

user_id
Type:unicode

The ID of the user who last triggered an update to the resource

type Sample

A single measurement for a given meter and resource.

Data samples:

Json
{
    "counter_name": "instance",
    "counter_type": "gauge",
    "counter_unit": "instance",
    "counter_volume": 1.0,
    "message_id": "5460acce-4fd6-480d-ab18-9735ec7b1996",
    "project_id": "35b17138-b364-4e6a-a131-8f3099c5be68",
    "resource_id": "bd9431c1-8d69-4ad3-803a-8d4a6b89fd36",
    "resource_metadata": {
        "name1": "value1",
        "name2": "value2"
    },
    "source": "openstack",
    "timestamp": "2015-05-07T15:37:20.888845",
    "user_id": "efd87807-12d2-4b38-9c70-5f5c2ac427ff"
}
XML
<value>
  <counter_name>instance</counter_name>
  <counter_type>gauge</counter_type>
  <counter_unit>instance</counter_unit>
  <counter_volume>1.0</counter_volume>
  <message_id>5460acce-4fd6-480d-ab18-9735ec7b1996</message_id>
  <project_id>35b17138-b364-4e6a-a131-8f3099c5be68</project_id>
  <resource_id>bd9431c1-8d69-4ad3-803a-8d4a6b89fd36</resource_id>
  <resource_metadata>
    <item>
      <key>name2</key>
      <value>value2</value>
    </item>
    <item>
      <key>name1</key>
      <value>value1</value>
    </item>
  </resource_metadata>
  <source>openstack</source>
  <timestamp>2015-05-07T15:37:20.888845</timestamp>
  <user_id>efd87807-12d2-4b38-9c70-5f5c2ac427ff</user_id>
</value>
counter_name
Type:unicode

The name of the meter

counter_type
Type:unicode

The type of the meter (see Measurements)

counter_unit
Type:unicode

The unit of measure for the value in counter_volume

counter_volume
Type:float

The actual measured value

message_id
Type:unicode

A unique identifier for the sample

project_id
Type:unicode

The ID of the project or tenant that owns the resource

resource_id
Type:unicode

The ID of the Resource for which the measurements are taken

resource_metadata
Type:dict(unicode: unicode)

Arbitrary metadata associated with the resource

source
Type:unicode

The ID of the source that identifies where the sample comes from

timestamp
Type:datetime

UTC date and time when the measurement was made

user_id
Type:unicode

The ID of the user who last triggered an update to the resource

type Statistics

Computed statistics for a query.

Data samples:

Json
{
    "avg": 4.5,
    "count": 10,
    "duration": 300.0,
    "duration_end": "2013-01-04T16:47:00",
    "duration_start": "2013-01-04T16:42:00",
    "max": 9.0,
    "min": 1.0,
    "period": 7200,
    "period_end": "2013-01-04T18:00:00",
    "period_start": "2013-01-04T16:00:00",
    "sum": 45.0,
    "unit": "GiB"
}
XML
<value>
  <avg>4.5</avg>
  <count>10</count>
  <duration>300.0</duration>
  <duration_end>2013-01-04T16:47:00</duration_end>
  <duration_start>2013-01-04T16:42:00</duration_start>
  <max>9.0</max>
  <min>1.0</min>
  <period>7200</period>
  <period_end>2013-01-04T18:00:00</period_end>
  <period_start>2013-01-04T16:00:00</period_start>
  <sum>45.0</sum>
  <unit>GiB</unit>
</value>
avg
Type:float

The average of all of the volume values seen in the data

count
Type:int

The number of samples seen

duration
Type:float

The difference, in seconds, between the oldest and newest timestamp

duration_end
Type:datetime

UTC date and time of the oldest timestamp, or the query end time

duration_start
Type:datetime

UTC date and time of the earliest timestamp, or the query start time

groupby
Type:dict(unicode: unicode)

Dictionary of field names for group, if groupby statistics are requested

max
Type:float

The maximum volume seen in the data

min
Type:float

The minimum volume seen in the data

period
Type:int

The difference, in seconds, between the period start and end

period_end
Type:datetime

UTC date and time of the period end

period_start
Type:datetime

UTC date and time of the period start

sum
Type:float

The total of all of the volume values seen in the data

unit
Type:unicode

The unit type of the data set

Alarms

type Alarm

Representation of an alarm.

Note

combination_rule and threshold_rule are mutually exclusive. The type of the alarm should be set to threshold or combination and the appropriate rule should be filled.

Data samples:

Json
{
    "alarm_actions": [
        "http://site:8000/alarm"
    ],
    "alarm_id": null,
    "combination_rule": {
        "alarm_ids": [
            "739e99cb-c2ec-4718-b900-332502355f38",
            "153462d0-a9b8-4b5b-8175-9e4b05e9b856"
        ],
        "operator": "or"
    },
    "description": "An alarm",
    "enabled": true,
    "insufficient_data_actions": [
        "http://site:8000/nodata"
    ],
    "name": "SwiftObjectAlarm",
    "ok_actions": [
        "http://site:8000/ok"
    ],
    "project_id": "c96c887c216949acbdfbd8b494863567",
    "repeat_actions": false,
    "state": "ok",
    "state_timestamp": "2015-05-07T15:37:21.053373",
    "threshold_rule": null,
    "timestamp": "2015-05-07T15:37:21.053367",
    "type": "combination",
    "user_id": "c96c887c216949acbdfbd8b494863567"
}
XML
<value>
  <alarm_actions>
    <item>http://site:8000/alarm</item>
  </alarm_actions>
  <alarm_id nil="true" />
  <combination_rule>
    <alarm_ids>
      <item>739e99cb-c2ec-4718-b900-332502355f38</item>
      <item>153462d0-a9b8-4b5b-8175-9e4b05e9b856</item>
    </alarm_ids>
    <operator>or</operator>
  </combination_rule>
  <description>An alarm</description>
  <enabled>true</enabled>
  <insufficient_data_actions>
    <item>http://site:8000/nodata</item>
  </insufficient_data_actions>
  <name>SwiftObjectAlarm</name>
  <ok_actions>
    <item>http://site:8000/ok</item>
  </ok_actions>
  <project_id>c96c887c216949acbdfbd8b494863567</project_id>
  <repeat_actions>false</repeat_actions>
  <state>ok</state>
  <state_timestamp>2015-05-07T15:37:21.053373</state_timestamp>
  <threshold_rule nil="true" />
  <timestamp>2015-05-07T15:37:21.053367</timestamp>
  <type>combination</type>
  <user_id>c96c887c216949acbdfbd8b494863567</user_id>
</value>
alarm_actions
Type:list(unicode)

The actions to do when alarm state change to alarm

alarm_id
Type:unicode

The UUID of the alarm

combination_rule
Type:AlarmCombinationRule

Describe when to trigger the alarm based on combining the state of other alarms

description
Type:unicode

The description of the alarm

enabled
Type:bool

This alarm is enabled?

insufficient_data_actions
Type:list(unicode)

The actions to do when alarm state change to insufficient data

name
Type:unicode

The name for the alarm

ok_actions
Type:list(unicode)

The actions to do when alarm state change to ok

project_id
Type:unicode

The ID of the project or tenant that owns the alarm

repeat_actions
Type:bool

The actions should be re-triggered on each evaluation cycle

state
Type:Enum(ok, alarm, insufficient data)

The state offset the alarm

state_timestamp
Type:datetime

The date of the last alarm state changed

threshold_rule
Type:AlarmThresholdRule

Describe when to trigger the alarm based on computed statistics

timestamp
Type:datetime

The date of the last alarm definition update

type
Type:Enum(threshold, combination)

Explicit type specifier to select which rule to follow below.

user_id
Type:unicode

The ID of the user who created the alarm

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

type Query

Sample query filter.

Data samples:

Json
{
    "field": "resource_id",
    "op": "eq",
    "type": "string",
    "value": "bd9431c1-8d69-4ad3-803a-8d4a6b89fd36"
}
XML
<value>
  <field>resource_id</field>
  <op>eq</op>
  <type>string</type>
  <value>bd9431c1-8d69-4ad3-803a-8d4a6b89fd36</value>
</value>
field
Type:unicode

The name of the field to test

op
Type:Enum(lt, le, eq, ne, ge, gt)

The comparison operator. Defaults to ‘eq’.

type
Type:unicode

The data type of value to compare against the stored data

value
Type:unicode

The value to compare against the stored data

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 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):

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

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.

Table Of Contents

Previous topic

V1 Web API

Next topic

Contributing to Ceilometer

This Page

Navigation

© Copyright 2013, OpenStack Foundation. Last updated on 2013.2.4.dev24.g292b4aa. Created using Sphinx 1.1.3.