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

b'<value>\n  <api>\n    <item>\n      <key>alarms:history:query:complex</key>\n      <value>true</value>\n    </item>\n    <item>\n      <key>alarms:history:query:simple</key>\n      <value>true</value>\n    </item>\n    <item>\n      <key>alarms:query:complex</key>\n      <value>true</value>\n    </item>\n    <item>\n      <key>alarms:query:simple</key>\n      <value>true</value>\n    </item>\n  </api>\n  <alarm_storage>\n    <item>\n      <key>storage:production_ready</key>\n      <value>true</value>\n    </item>\n  </alarm_storage>\n</value>'

alarm_storage¶

Type:: dict(str: bool)

A flattened dictionary of alarm storage capabilities

api¶

Type:: dict(str: 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.

Data samples:

Json

{
    "alarm_actions": [
        "http://site:8000/alarm"
    ],
    "alarm_id": null,
    "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_reason": "threshold over 90%",
    "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": "gnocchi_aggregation_by_metrics_threshold",
    "user_id": "c96c887c216949acbdfbd8b494863567"
}

XML

b'<value>\n  <alarm_id nil="true" />\n  <name>SwiftObjectAlarm</name>\n  <description>An alarm</description>\n  <enabled>true</enabled>\n  <ok_actions>\n    <item>http://site:8000/ok</item>\n  </ok_actions>\n  <alarm_actions>\n    <item>http://site:8000/alarm</item>\n  </alarm_actions>\n  <insufficient_data_actions>\n    <item>http://site:8000/nodata</item>\n  </insufficient_data_actions>\n  <repeat_actions>false</repeat_actions>\n  <type>gnocchi_aggregation_by_metrics_threshold</type>\n  <time_constraints>\n    <item>\n      <name>SampleConstraint</name>\n      <description>nightly build every night at 23h for 3 hours</description>\n      <start>0 23 * * *</start>\n      <duration>10800</duration>\n      <timezone>Europe/Ljubljana</timezone>\n    </item>\n  </time_constraints>\n  <project_id>c96c887c216949acbdfbd8b494863567</project_id>\n  <user_id>c96c887c216949acbdfbd8b494863567</user_id>\n  <timestamp>2015-01-01T12:00:00</timestamp>\n  <state>ok</state>\n  <state_timestamp>2015-01-01T12:00:00</state_timestamp>\n  <state_reason>threshold over 90%</state_reason>\n  <severity>moderate</severity>\n</value>'

alarm_actions¶

Type:: list(str)

The actions to do when alarm state change to alarm

alarm_id¶

Type:: str

The UUID of the alarm

property description¶: The description of the alarm

enabled¶

Type:: bool

This alarm is enabled?

evaluate_timestamp¶

Type:: datetime

The latest alarm evaluation time

insufficient_data_actions¶

Type:: list(str)

The actions to do when alarm state change to insufficient data

name¶

Type:: str

The name for the alarm

ok_actions¶

Type:: list(str)

The actions to do when alarm state change to ok

project_id¶

Type:: str

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

property severity¶: The severity of the alarm

property state¶: The state offset the alarm

state_reason¶

Type:: str

The reason of the current state

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

property type¶: Explicit type specifier to select which rule to follow below.

user_id¶

Type:: str

The ID of the user who created the alarm

type MetricOfResourceRule¶

Data samples:

Json

{
    "comparison_operator": "eq",
    "evaluation_periods": 1,
    "granularity": 60
}

XML

b'<value>\n  <comparison_operator>eq</comparison_operator>\n  <evaluation_periods>1</evaluation_periods>\n  <granularity>60</granularity>\n</value>'

aggregation_method¶

Type:: str

The aggregation_method to compare to the threshold

property comparison_operator¶

evaluation_periods¶

Type:: integer

The number of historical periods to evaluate the threshold

granularity¶

Type:: integer

The time range in seconds over which query

metric¶

Type:: str

The name of the metric

resource_id¶

Type:: str

The id of a resource

resource_type¶

Type:: str

The resource type

threshold¶

Type:: float

The threshold of the alarm

type AggregationMetricByResourcesLookupRule¶

Data samples:

Json

{
    "comparison_operator": "eq",
    "evaluation_periods": 1,
    "granularity": 60
}

XML

b'<value>\n  <comparison_operator>eq</comparison_operator>\n  <evaluation_periods>1</evaluation_periods>\n  <granularity>60</granularity>\n</value>'

aggregation_method¶

Type:: str

The aggregation_method to compare to the threshold

property comparison_operator¶

evaluation_periods¶

Type:: integer

The number of historical periods to evaluate the threshold

granularity¶

Type:: integer

The time range in seconds over which query

metric¶

Type:: str

The name of the metric

query¶

Type:: str

The query to filter the metric, Don’t forget to filter out deleted resources (example: {“and”: [{“=”: {“ended_at”: null}}, …]}), Otherwise Gnocchi will try to create the aggregate against obsolete resources

resource_type¶

Type:: str

The resource type

threshold¶

Type:: float

The threshold of the alarm

type AggregationMetricsByIdLookupRule¶

Data samples:

Json

{
    "comparison_operator": "eq",
    "evaluation_periods": 1,
    "granularity": 60
}

XML

b'<value>\n  <comparison_operator>eq</comparison_operator>\n  <evaluation_periods>1</evaluation_periods>\n  <granularity>60</granularity>\n</value>'

aggregation_method¶

Type:: str

The aggregation_method to compare to the threshold

property comparison_operator¶

evaluation_periods¶

Type:: integer

The number of historical periods to evaluate the threshold

granularity¶

Type:: integer

The time range in seconds over which query

metrics¶

Type:: list(str)

A list of metric Ids

threshold¶

Type:: float

The threshold of the alarm

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

b'<value>\n  <name>SampleConstraint</name>\n  <description>nightly build every night at 23h for 3 hours</description>\n  <start>0 23 * * *</start>\n  <duration>10800</duration>\n  <timezone>Europe/Ljubljana</timezone>\n</value>'

property description¶: The description of the constraint

duration¶

Type:: integer

How long the constraint should last, in seconds

name¶

Type:: str

The name of the constraint

start¶

Type:: cron

Start point of the time constraint, in cron format

timezone¶

Type:: str

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

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

alarm_id¶

Type:: str

The UUID of the alarm

detail¶

Type:: str

JSON fragment describing change

event_id¶

Type:: str

The UUID of the change event

on_behalf_of¶

Type:: str

The tenant on behalf of which the change is being made

project_id¶

Type:: str

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

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.

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

b'<value>\n  <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>\n  <orderby>[{"counter_volume": "ASC"}, {"timestamp": "DESC"}]</orderby>\n  <limit>42</limit>\n</value>'

filter¶

Type:: str

The filter expression encoded in json.

limit¶

Type:: int

The maximum number of results to be returned.

orderby¶

Type:: str

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,
    "meters": [
        "f6857d3f-bde6-441a-aa1d-e98fa4ea543f",
        "ea1491ca-5309-4b5a-9f05-34409c6e8b6c"
    ],
    "type": "gnocchi_resources_threshold"
}

V2 Web API

V2 Web API¶

Capabilities¶

Alarms¶

Filtering Queries¶

Composite rule Alarm¶

aodh 20.1.0.dev44

Page Contents