List Alarms

Overview

  • Lists alarms, based on a query.

  • This API performs the same function as "OpenStack Telemetry API: GET /v2/alarms".

Classification

  • List

API Operation Object

  • Alarm

Synchronous / Asynchronous

  • Synchronous

Request

HTTP Request Method

  • GET

HTTP Request Path

{api_endpoint}/v2/alarms

HTTP Request Header

Content-Type: application/json
Accept: application/json
X-Auth-Token: <token_id>

HTTP Request Body

  • none

Request Parameter

name

style

format

description

required/optional

default value

action for invalid parameter

response code for invalid parameter

q

Query

string

Filter rules for listing alarms

optional

-

Terminate

400

page

Query

Integer

A page number when alarms are paginated

optional

100

Terminate

400

per_page

Query

Integer

A page number when alarms are paginated

optional

100

Terminate

400

token_id

Header

authentication token string

authentication token

required

-

Terminate

401

A query key can be designated by describing after a dot(.) . (ex. q.field, q.op)

Valid query keys

key name

format

description

required/optional

default value

field

string

a retrieving target

required

-

op

string

a comparison operator

optional

eq

value

string

a field value for retrieving meter statistics

required

-

type

string

format used to convert the value for comparison

optional

-

A query field can be designated by describing after "q.field=". (ex. q.field=timestamp)

Valid query fields

key name

format

description

required/optional

default value

valid operator

alarm_id

string

the uuid of an alarm

optional

-

eq

project_id

string

the uuid of a tenant

optional

-

eq

project

string

an alias of 'project_id'

optional

-

eq

user_id

string

the uuid of a user

optional

-

eq

user

string

an alias of 'user_id'

optional

-

eq

name

string

the name of an alarm

optional

-

eq

enabled

boolean

whether an alarm is enabled or disabled

optional

-

eq

state

string

the state of an alarm

optional

-

eq

meter

string

the meter name to which an alarm belongs

optional

-

eq

type

string

the type of an alarm

optional

-

eq

alarm_type

string

an alias of 'type'

optional

-

eq

severity

string

the severity of an alarm

optional

-

eq

A query operator can be designated by describing after "q.op=". (ex. q.op=eq)

Valid operators in a query

operator

description

eq

equal to

A query type can be designated by describing after "q.type=". (ex. q.type=integer)

Valid types in a query

type

ex. (q.value)

integer

1234

float

1234.1234

boolean

0 or 1

string

abcd

datetime

2015-12-01T12:34:00+09:00

Response

Response Header

Format

HTTP/1.1 <response_code> <status>       (ex. 200 OK)
  • <response_code>: see "Response Code" section

  • <status>: message based on the response code

注釈

skip auto-insert fields such as "Content-Length" and "Date"

Response Code

Response Codes

response code

status

condition

message

200

ok

normal end

400

bad request

specified non query field

Field can't be blank.

invalid query field

Unrecognized field in query. valid keys: ["alarm_id", "enabled", "meter", "name", "project_id", "state", "type", "severity", "user_id"]

invalid query op

Unimplemented operator 'xxxx' for specified field.

specified non query value

Value can't be blank.

invalid query data type

The data type 'xxxx' is not supported. The supported data type list is: ['integer', 'float', 'boolean', 'string', 'datetime']

invalid value (1)

Unable to convert the value 'xxxx' to the expected data type 'integer'.

invalid value (2)

Unexpected exception converting 'xxxx' to the expected data type 'datetime'.

401

unauthorized

authentication failure

The request you have made requires authentication.

invalid project id

Not authorized to access project.

500

internal server error

internal server error

The request processing has failed due to some unknown error, exception or failure

Response Body

Format

[
    {
        "alarm_id": "<alarm_id>",
        "project_id": "<tenant_id>",
        "user_id": "<user_id>",
        "name": "<alarm_name>",
        "description": "<alarm_description>",
        "enabled": <enabled>,
        "state": "<state>",
        "repeat_actions": <repeat_actions>,
        "severity": "<severity>",
        "time_constraints": [],
        "alarm_actions": ["<alarm_actions>",<<repeat>>],
        "ok_actions": ["<ok_actions>",<<repeat>>],
        "insufficient_data_actions": [],
        "type": "threshold",
        "threshold_rule": {
            "meter_name": "<meter_name>",
            "period": <period>,
            "query": [{
                "field": "resource_id",
                "op": "eq",
                "type": "string",
                "value": "<resource_id>"
            }],
            "exclude_outliers": false,
            "evaluation_periods": <evaluation_periods>,
            "evaluation_type": "<evaluation_type>",
            "comparison_operator": "<comparison_operator>",
            "statistic": "<statistics>",
            "threshold": <threshold>
        },
        "timestamp": "<timestamp>",
        "state_timestamp": "<state_timestamp>",
        "resource_name": "<resource_name>",
        "deleted": <deleted>
    },
    <<repeat>>
]

Response Parameter

item

format

description

(data)

List(Alarm)

alarms listed by the request

Sample Request and Response

Sample API Request

Request URL

GET /v2/alarms/?q.field=alarm_id&q.op=eq&q.type=string&q.value=638c3bfe-9435-45f5-9fbb-9d6d380c17ba&page=1&per_page=10

Request Header

Content-Type: application/json
Accept: application/json
X-Auth-Token: e8c788fbaeb14964ae19759eb1df4ff1

Request Body

  • none

Sample API Response

Response Header

HTTP/1.1 200 OK

Response Body

[
    {
        "alarm_id": "638c3bfe-9435-45f5-9fbb-9d6d380c17ba",
        "project_id": "26574d10673044dbb03ffc8facc7ab7a",
        "user_id": "a9de93f5a7604707a2870d8b95f74eda",
        "name": "alarm-test",
        "description": "alarm-test-description",
        "enabled": true,
        "state": "ok",
        "repeat_actions": false,
        "severity": "moderate",
        "time_constraints": [],
        "alarm_actions": ["http://example.com"],
        "ok_actions": ["http://example.com"],
        "insufficient_data_actions": [],
        "type": "threshold",
        "threshold_rule": {
            "meter_name": "nova.hv.status.bool",
            "period": 300,
            "query": [{
                "field": "resource_id",
                "op": "eq",
                "type": "string",
                "value": "nova_5dd5bfe5-aee8-4663-86e4-e76d032d318e"
            }],
            "exclude_outliers": false,
            "evaluation_periods": 1,
            "evaluation_type": "0",
            "comparison_operator": "gt",
            "statistic": "max",
            "threshold": 1
        },
        "timestamp": "2015-11-23T04:35:08+00:00",
        "state_timestamp": "2015-11-20T07:05:10+00:00",
        "resource_name": "test-vm",
        "deleted": false
    }
]

Sample Error Response

HTTP Request

GET /v2/alarms?q.field=hoge&q.value=hoge
User-Agent: curl/7.35.0
Content-Type: application/json
Accept: application/json
X-Auth-Token: 61389973e52b49c394ba3b89179b290b

HTTP Response

HTTP/1.1 400 Bad Request
Date: Mon, 09 Nov 2015 04:36:02 GMT
Server: Apache
Cache-Control: no-cache
X-XSS-Protection: 1; mode=block
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
Status: 400 Bad Request
Connection: close
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8

{"error":{"code":400,"message":"Unrecognized field in query. valid keys: [\"alarm_id\", \"enabled\", \"meter\", \"name\", \"project_id\", \"state\", \"type\", \"severity\", \"user_id\"]","title":"Bad Request"}}