V2 Web API

Capabilities

The Capabilities API allows you to directly discover which functions from the V2 API functionality, including the selectable aggregate functions, are supported by the currently configured storage driver. A capabilities query returns a flattened dictionary of properties with associated boolean values - a ‘False’ or absent value means that the corresponding feature is not available in the backend.

GET /v2/capabilities

Returns a flattened dictionary of API capabilities.

Capabilities supported by the currently configured storage driver.

Return type:Capabilities
type Capabilities

A representation of the API and storage capabilities.

Usually constrained by restrictions imposed by the storage driver.

Data samples:

Json
{
    "alarm_storage": {
        "storage:production_ready": true
    }, 
    "api": {
        "alarms:history:query:complex": true, 
        "alarms:history:query:simple": true, 
        "alarms:query:complex": true, 
        "alarms:query:simple": true
    }
}
XML
<value>
  <api>
    <item>
      <key>alarms:history:query:complex</key>
      <value>true</value>
    </item>
    <item>
      <key>alarms:query:complex</key>
      <value>true</value>
    </item>
    <item>
      <key>alarms:query:simple</key>
      <value>true</value>
    </item>
    <item>
      <key>alarms:history:query:simple</key>
      <value>true</value>
    </item>
  </api>
  <alarm_storage>
    <item>
      <key>storage:production_ready</key>
      <value>true</value>
    </item>
  </alarm_storage>
</value>
alarm_storage
Type:dict(unicode: bool)

A flattened dictionary of alarm storage capabilities

api
Type:dict(unicode: bool)

A flattened dictionary of API capabilities

Alarms

GET /v2/alarms

Return all alarms, based on the query provided.

Parameters:
  • q (list(Query)) – Filter rules for the alarms to be returned.
  • sort (list(str)) – A list of pairs of sort key and sort dir.
  • limit (int) – The maximum number of items to be return.
  • marker (str) – The pagination query marker.
Return type:

list(Alarm)
POST /v2/alarms

Create a new alarm.

Parameters:
  • data (Alarm) – an alarm within the request body.
Return type:

Alarm
GET /v2/alarms/(alarm_id)

Return this alarm.

Return type:Alarm
PUT /v2/alarms/(alarm_id)

Modify this alarm.

Parameters:
  • data (Alarm) – an alarm within the request body.
Return type:

Alarm
DELETE /v2/alarms/(alarm_id)

Delete this alarm.

GET /v2/alarms/(alarm_id)/history

Assembles the alarm history requested.

Parameters:
  • q (list(Query)) – Filter rules for the changes to be described.
  • sort (list(str)) – A list of pairs of sort key and sort dir.
  • limit (int) – The maximum number of items to be return.
  • marker (str) – The pagination query marker.
Return type:

list(AlarmChange)
PUT /v2/alarms/(alarm_id)/state

Set the state of this alarm.

Parameters:
  • state (Enum(ok, alarm, insufficient data)) – an alarm state within the request body.
Return type:

Enum(ok, alarm, insufficient data)
GET /v2/alarms/(alarm_id)/state

Get the state of this alarm.

Return type:Enum(ok, alarm, insufficient data)
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, 
    "severity": "moderate", 
    "state": "ok", 
    "state_timestamp": "2015-01-01T12:00:00", 
    "time_constraints": [
        {
            "description": "nightly build every night at 23h for 3 hours", 
            "duration": 10800, 
            "name": "SampleConstraint", 
            "start": "0 23 * * *", 
            "timezone": "Europe/Ljubljana"
        }
    ], 
    "timestamp": "2015-01-01T12:00:00", 
    "type": "combination", 
    "user_id": "c96c887c216949acbdfbd8b494863567"
}
XML
<value>
  <alarm_id nil="true" />
  <name>SwiftObjectAlarm</name>
  <description>An alarm</description>
  <enabled>true</enabled>
  <ok_actions>
    <item>http://site:8000/ok</item>
  </ok_actions>
  <alarm_actions>
    <item>http://site:8000/alarm</item>
  </alarm_actions>
  <insufficient_data_actions>
    <item>http://site:8000/nodata</item>
  </insufficient_data_actions>
  <repeat_actions>false</repeat_actions>
  <type>combination</type>
  <time_constraints>
    <item>
      <name>SampleConstraint</name>
      <description>nightly build every night at 23h for 3 hours</description>
      <start>0 23 * * *</start>
      <duration>10800</duration>
      <timezone>Europe/Ljubljana</timezone>
    </item>
  </time_constraints>
  <project_id>c96c887c216949acbdfbd8b494863567</project_id>
  <user_id>c96c887c216949acbdfbd8b494863567</user_id>
  <timestamp>2015-01-01T12:00:00</timestamp>
  <state>ok</state>
  <state_timestamp>2015-01-01T12:00:00</state_timestamp>
  <severity>moderate</severity>
  <combination_rule>
    <operator>or</operator>
    <alarm_ids>
      <item>739e99cb-c2ec-4718-b900-332502355f38</item>
      <item>153462d0-a9b8-4b5b-8175-9e4b05e9b856</item>
    </alarm_ids>
  </combination_rule>
</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

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

severity
Type:Enum(low, moderate, critical)

The severity of the alarm

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

The state offset the alarm

state_timestamp
Type:datetime

The date of the last alarm state changed

time_constraints
Type:list(AlarmTimeConstraint)

Describe time constraints for the alarm

timestamp
Type:datetime

The date of the last alarm definition update

type
Type:Enum(gnocchi_aggregation_by_metrics_threshold, combination, composite, gnocchi_resources_threshold, gnocchi_aggregation_by_resources_threshold, threshold, event)

Explicit type specifier to select which rule to follow below.

user_id
Type:unicode

The ID of the user who created the alarm

type AlarmThresholdRule

Alarm Threshold Rule

Describe when to trigger the alarm based on computed statistics

Data samples:

Json
{
    "comparison_operator": "gt", 
    "evaluation_periods": 1, 
    "exclude_outliers": false, 
    "meter_name": "cpu_util", 
    "period": 60, 
    "query": [
        {
            "field": "resource_id", 
            "op": "eq", 
            "type": "string", 
            "value": "2a4d689b-f0b8-49c1-9eef-87cae58d80db"
        }
    ], 
    "statistic": "avg", 
    "threshold": 300.0
}
XML
<value>
  <meter_name>cpu_util</meter_name>
  <query>
    <item>
      <field>resource_id</field>
      <op>eq</op>
      <value>2a4d689b-f0b8-49c1-9eef-87cae58d80db</value>
      <type>string</type>
    </item>
  </query>
  <period>60</period>
  <comparison_operator>gt</comparison_operator>
  <threshold>300.0</threshold>
  <statistic>avg</statistic>
  <evaluation_periods>1</evaluation_periods>
  <exclude_outliers>false</exclude_outliers>
</value>
comparison_operator
Type:Enum(lt, le, eq, ne, ge, gt)

The comparison against the alarm threshold

evaluation_periods
Type:integer

The number of historical periods to evaluate the threshold

exclude_outliers
Type:bool

Whether datapoints with anomalously low sample counts are excluded

meter_name
Type:unicode

The name of the meter

period
Type:integer

The time range in seconds over which query

query
Type:list(Query)

The query to find the data for computing statistics. Ownership settings are automatically included based on the Alarm owner.

statistic
Type:Enum(max, min, avg, sum, count)

The statistic to compare to the threshold

threshold
Type:float

The threshold of the alarm

type AlarmCombinationRule

Alarm Combination Rule

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

Data samples:

Json
{
    "alarm_ids": [
        "739e99cb-c2ec-4718-b900-332502355f38", 
        "153462d0-a9b8-4b5b-8175-9e4b05e9b856"
    ], 
    "operator": "or"
}
XML
<value>
  <operator>or</operator>
  <alarm_ids>
    <item>739e99cb-c2ec-4718-b900-332502355f38</item>
    <item>153462d0-a9b8-4b5b-8175-9e4b05e9b856</item>
  </alarm_ids>
</value>
alarm_ids
Type:list(unicode)

List of alarm identifiers to combine

operator
Type:Enum(or, and)

How to combine the sub-alarms

type MetricOfResourceRule

Data samples:

Json
{
    "comparison_operator": "eq", 
    "evaluation_periods": 1, 
    "granularity": 60
}
XML
<value>
  <comparison_operator>eq</comparison_operator>
  <evaluation_periods>1</evaluation_periods>
  <granularity>60</granularity>
</value>
metric
Type:unicode

The name of the metric

resource_id
Type:unicode

The id of a resource

resource_type
Type:unicode

The resource type

type AggregationMetricByResourcesLookupRule

Data samples:

Json
{
    "comparison_operator": "eq", 
    "evaluation_periods": 1, 
    "granularity": 60
}
XML
<value>
  <comparison_operator>eq</comparison_operator>
  <evaluation_periods>1</evaluation_periods>
  <granularity>60</granularity>
</value>
metric
Type:unicode

The name of the metric

resource_type
Type:unicode

The resource type

type AggregationMetricsByIdLookupRule

Data samples:

Json
{
    "comparison_operator": "eq", 
    "evaluation_periods": 1, 
    "granularity": 60
}
XML
<value>
  <comparison_operator>eq</comparison_operator>
  <evaluation_periods>1</evaluation_periods>
  <granularity>60</granularity>
</value>
metrics
Type:list(unicode)

A list of metric Ids

type AlarmTimeConstraint

Representation of a time constraint on an alarm.

Data samples:

Json
{
    "description": "nightly build every night at 23h for 3 hours", 
    "duration": 10800, 
    "name": "SampleConstraint", 
    "start": "0 23 * * *", 
    "timezone": "Europe/Ljubljana"
}
XML
<value>
  <name>SampleConstraint</name>
  <description>nightly build every night at 23h for 3 hours</description>
  <start>0 23 * * *</start>
  <duration>10800</duration>
  <timezone>Europe/Ljubljana</timezone>
</value>
description
Type:unicode

The description of the constraint

duration
Type:integer

How long the constraint should last, in seconds

name
Type:unicode

The name of the constraint

start
Type:cron

Start point of the time constraint, in cron format

timezone
Type:unicode

Timezone of the constraint

type AlarmChange

Representation of an event in an alarm’s history.

Data samples:

Json
{
    "alarm_id": "e8ff32f772a44a478182c3fe1f7cad6a", 
    "detail": "{\"threshold\": 42.0, \"evaluation_periods\": 4}", 
    "on_behalf_of": "92159030020611e3b26dde429e99ee8c", 
    "project_id": "b6f16144010811e387e4de429e99ee8c", 
    "timestamp": "2015-01-01T12:00:00", 
    "type": "rule change", 
    "user_id": "3e5d11fda79448ac99ccefb20be187ca"
}
XML
<value>
  <alarm_id>e8ff32f772a44a478182c3fe1f7cad6a</alarm_id>
  <type>rule change</type>
  <detail>{"threshold": 42.0, "evaluation_periods": 4}</detail>
  <project_id>b6f16144010811e387e4de429e99ee8c</project_id>
  <user_id>3e5d11fda79448ac99ccefb20be187ca</user_id>
  <on_behalf_of>92159030020611e3b26dde429e99ee8c</on_behalf_of>
  <timestamp>2015-01-01T12:00:00</timestamp>
</value>
alarm_id
Type:unicode

The UUID of the alarm

detail
Type:unicode

JSON fragment describing change

event_id
Type:unicode

The UUID of the change event

on_behalf_of
Type:unicode

The tenant on behalf of which the change is being made

project_id
Type:unicode

The project ID of the initiating identity

timestamp
Type:datetime

The time/date of the alarm change

type
Type:Enum(creation, rule change, state transition, deletion)

The type of change

user_id
Type:unicode

The user ID of the initiating identity

Filtering Queries

The filter expressions of the query feature operate on the fields of 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. On the other hand, SQL based DB engine will return empty result as the join operation on the metadata table will return zero rows 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.

POST /v2/query/alarms

Define query for retrieving Alarm data.

Parameters:
  • body (ComplexQuery) – Query rules for the alarms to be returned.
Return type:

list(Alarm)
POST /v2/query/alarms/history

Define query for retrieving AlarmChange data.

Parameters:
  • body (ComplexQuery) – Query rules for the alarm history to be returned.
Return type:

list(AlarmChange)
type ComplexQuery

Holds a sample query encoded in json.

Data samples:

Json
{
    "filter": "{\"and\": [{\"and\": [{\"=\": {\"counter_name\": \"cpu_util\"}}, {\">\": {\"counter_volume\": 0.23}}, {\"<\": {\"counter_volume\": 0.26}}]}, {\"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\"}}]}]}]}", 
    "limit": 42, 
    "orderby": "[{\"counter_volume\": \"ASC\"}, {\"timestamp\": \"DESC\"}]"
}
XML
<value>
  <filter>{"and": [{"and": [{"=": {"counter_name": "cpu_util"}}, {"&gt;": {"counter_volume": 0.23}}, {"&lt;": {"counter_volume": 0.26}}]}, {"or": [{"and": [{"&gt;": {"timestamp": "2013-12-01T18:00:00"}}, {"&lt;": {"timestamp": "2013-12-01T18:15:00"}}]}, {"and": [{"&gt;": {"timestamp": "2013-12-01T18:30:00"}}, {"&lt;": {"timestamp": "2013-12-01T18:45:00"}}]}]}]}</filter>
  <orderby>[{"counter_volume": "ASC"}, {"timestamp": "DESC"}]</orderby>
  <limit>42</limit>
</value>
filter
Type:unicode

The filter expression encoded in json.

limit
Type:int

The maximum number of results to be returned.

orderby
Type:unicode

List of single-element dicts for specifing the ordering of the results.

Composite rule Alarm

The composite type alarm allows users to specify a composite rule to define an alarm with multiple triggering conditions, using a combination of and and or relations. A composite rule is composed of multiple threshold rules or gnocchi rules. A sample composite alarm request form is as follows:

{
    "name": "test_composite",
    "type": "composite",
    "composite_rule": {
        "and": [THRESHOLD_RULE1, THRESHOLD_RULE2, {
            'or': [THRESHOLD_RULE3, GNOCCHI_RULE1,
                   GNOCCHI_RULE2, GNOCCHI_RULE3]
        }]
    }
}

A sub-rule in composite_rule is same as a threshold_rule in threshold alarm or a gnocchi_rule in gnocchi alarm. Additionally it has a mandatory type field to specify the rule type, like in the following sample:

{
    "threshold": 0.8,
    "meter_name": "cpu_util",
    "type": "threshold"
}

Table Of Contents

Previous topic

Web API

Next topic

Installing Aodh

Project Source

This Page

Navigation

© Copyright 2012-2015, OpenStack Foundation. Last updated on 'Wed Sep 27 15:21:31 2017, commit efa09fa'. Created using Sphinx 1.2.3.