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
- 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.
- PUT /v2/alarms/(alarm_id)¶
Modify this 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>'
- metric¶
- Type
str
The name of the metric
- resource_id¶
- Type
str
The id of a resource
- resource_type¶
- Type
str
The resource type
- 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>'
- 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
- 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>'
- metrics¶
- Type
list(str)
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
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"}}, {">": {"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"}}]}]}]}</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"
}