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.
-
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¶
-
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
-
description
¶ Type: str The description of the alarm
-
enabled
¶ Type: bool This alarm is enabled?
-
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
-
severity
¶ Type: Enum(low, moderate, critical) The severity of the alarm
-
state
¶ Type: Enum(ok, alarm, insufficient data) 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
-
type
¶ Type: Enum(composite, event, gnocchi_aggregation_by_metrics_threshold, gnocchi_aggregation_by_resources_threshold, gnocchi_resources_threshold, loadbalancer_member_health) 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>'
-
description
¶ Type: str 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.
-
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"
}