Alarms¶

Alarms bind alerting rules, entities, and notification plans into a logical unit. Alarms are responsible for determining a state (OK, WARNING or CRITICAL) based on the result of a check, and executing a notification plan whenever that state changes. You create alerting rules by using the alarm domain-specific language (DSL).

For information about using the DSL, see Alert Triggering and Alarms. For alarm examples by check, see Alarm examples.

The following table describes the attributes for the Alarms API resource:

Name	Description	Validation
check_id	The ID of the check to alert on.	Immutable String
notification_plan_id	The id of the notification plan to execute when the state changes.	Valid notification plan Non-empty string
criteria	The alarm DSL for describing alerting conditions and their output states.	Optional String between 1 and 16384 characters long Valid alarm
disabled	Disables the alarm.	Optional Boolean
label	A friendly label for a check.	Optional String between 1 and 255 characters long
metadata	Arbitrary key/value pairs.	Optional Hash [String,String between 1 and 255 characters long: Optional] Array or object with number of items between 0 and 256

Use the following alarms API operations to create, view, and manage alarm resources.

Create an alarm ¶

POST /entities/{entityId}/alarms

Create a new alarm by using a valid set of attributes from the alarms attributes table.

For more information, see Alarm language.

The following table shows the possible response codes for this operation:

Response Code	Name	Description
201	Accepted	The location header contains a link to the newly created alarm.
400	Bad request	The system received an invalid value in a request.
401	Unauthorized	The system received a request from a user that is not authenticated.
403	Forbidden	The system received a request that the user is not authorized to make.
500	Internal Server Error	An unexpected condition was encountered.
503	Service Unavailable	The system is experiencing heavy load or another system failure.

Request¶

The following table shows the header parameters for the request:

Name	Type	Description
X-Auth-Token	String (Required)	A valid authentication token with administrative access. For details, see Get your credentials

Example Create alarm: JSON request

{
    "check_id": "chAAAA",
    "criteria": "if (metric[\"duration\"] >= 2) { return new AlarmStatus(OK); } return new AlarmStatus(CRITICAL);",
    "notification_plan_id": "npAAAAA"
}

Response¶

This operation does not return a response body.

Test an alarm ¶

POST /entities/{entityId}/test-alarm

The test_alarm endpoint is used to post alarm criteria and alarm data to test whether the alarm criteria is valid and to show how the alarm state is evaluated. You cannot specify an existing alarm ID with this endpoint; instead, you provide the alarm’s criteria within the request. The test_alarm response not only provides the final evaluated state, but also includes all state transitions noticed during the calculation.

To test an alarm, you need to provide one or more observations. An observation consists of a set of metrics from a single data center, such as DFW, LON, and IAD. A group of observations consist of a set of metrics from more than one data center.

Cloud Monitoring passes the observation(s) that you provide to the event processors, and then captures and returns an array of all state changes in the same order that they were evaluated. The state returned by the test alarm depends both upon the criteria and the metrics provided for the test alarm. For example, if you have a criteria that returns “CRITICAL” if a certain metric is above a threshold and “OK” otherwise, you should expect to receive a “CRITICAL” response if you provide a metric with a value above that threshold and an “OK” response if you provide a metric with a value below that threshold.

When you test an alarm, you provide a list of check data, which you can retrieve from a test check operation.

Note

A consecutiveCount of 1 is always used for these calls. If another value is set in your criteria it is overridden.

The following table shows the possible response codes for this operation:

Response Code	Name	Description
200	OK	The request completed.
400	Bad request	The system received an invalid value in a request.
401	Unauthorized	The system received a request from a user that is not authenticated.
403	Forbidden	The system received a request that the user is not authorized to make.
500	Internal Server Error	An unexpected condition was encountered.
503	Service Unavailable	The system is experiencing heavy load or another system failure.

Request¶

The following table shows the header parameters for the request:

Name	Type	Description
X-Auth-Token	String (Required)	A valid authentication token with administrative access. For details, see Get your credentials

Example Test alarms criteria

:set consecutiveCount=1
    if (metric["busy_workers"] > 2) {
      return new AlarmStatus(WARNING);
    }
    if (metric["busy_workers"] > 3) {
      return new AlarmStatus(CRITICAL);
    }
    return new AlarmStatus(OK);

Example Test alarm: JSON request

{
    "criteria": "if (metric[\"code\"] == \"404\") { return new AlarmStatus(CRITICAL, \"not found\"); } return new AlarmStatus(OK);",
    "check_data": [
        {
            "timestamp": 1319222001982,
            "monitoring_zone_id": "mzxJ4L2IU",
            "available": true,
            "status": "code=200,rt=0.257s,bytes=0",
            "metrics": {
                "bytes": {
                    "type": "i",
                    "data": "0"
                },
                "tt_firstbyte": {
                    "type": "I",
                    "data": "257"
                },
                "tt_connect": {
                    "type": "I",
                    "data": "128"
                },
                "code": {
                    "type": "s",
                    "data": "200"
                },
                "duration": {
                    "type": "I",
                    "data": "257"
                }
            }
        }
    ]
}

Response¶

Example Test alarm: JSON response

[
    {
        "timestamp": 1319224500831,
        "state": "OK",
        "status": "Matched default return statement"
    }
]

Example Test alarm, multi-state: JSON response

[
    {
        "state": "OK",
        "status": "Ping responds as expected.",
        "timestamp": "1417732774575"
    },
    {
        "state": "WARNING",
        "status": "blah.",
        "timestamp": "1417732795200"
    },
    {
        "state": "CRITICAL",
        "status": "cnt=6,avail=0,min=-nan,max=-nan,avg=-nan",
        "timestamp": "1417732795216"
    }
]

List alarms ¶

GET /entities/{entityId}/alarms

List the alarms on the specified entityId. Use /alarms?id=alarmOneId & id=alarmTwoId to filter the results to only include information about the specified alarms.

This operation can be paginated. For information, see Paginated collections.

The following table shows the possible response codes for this operation:

Response Code	Name	Description
200	OK	The request completed.
401	Unauthorized	The system received a request from a user that is not authenticated.
403	Forbidden	The system received a request that the user is not authorized to make.
500	Internal Server Error	An unexpected condition was encountered.
503	Service Unavailable	The system is experiencing heavy load or another system failure.

Request¶

The following table shows the header parameters for the request:

Name	Type	Description
X-Auth-Token	String (Required)	A valid authentication token with administrative access. For details, see Get your credentials

Note

This operation does not accept a request body.

Response¶

Example List alarms: JSON response

{
    "values": [
        {
            "id": "alAAAA",
            "check_id": "chAAAA",
            "entity_id": "enZZZZA",
            "criteria": "if (metric[\"duration\"] >= 2) { return new AlarmStatus(OK); } return new AlarmStatus(CRITICAL);"
        }
    ],
    "metadata": {
        "count": 1,
        "limit": 50,
        "marker": null,
        "next_marker": null,
        "next_href": null
    }
}

Get alarm by ID ¶

GET /entities/{entityId}/alarms/{alarmId}

Get information for a single alarm.

The following table shows the possible response codes for this operation:

Response Code	Name	Description
200	OK	The request completed.
401	Unauthorized	The system received a request from a user that is not authenticated.
403	Forbidden	The system received a request that the user is not authorized to make.
500	Internal Server Error	An unexpected condition was encountered.
503	Service Unavailable	The system is experiencing heavy load or another system failure.

Request¶

The following table shows the header parameters for the request:

Name	Type	Description
X-Auth-Token	String (Required)	A valid authentication token with administrative access. For details, see Get your credentials

Note

This operation does not accept a request body.

Response¶

Example Get alarms by ID: JSON response

{
    "id": "alAAAA",
    "check_id": "chAAAA",
    "entity_id": "enZZZZA",
    "criteria": "if (metric[\"duration\"] >= 2) { return new AlarmStatus(OK); } return new AlarmStatus(CRITICAL);"
}

Update alarm by ID ¶

PUT /entities/{entityId}/alarms/{alarmId}

Update an alarm by using a valid set of attributes from the alarms attributes table.

The following table shows the possible response codes for this operation:

Response Code	Name	Description
204	No Content	The server has fulfilled the request. Does not return a response body.
400	Bad request	The system received an invalid value in a request.
401	Unauthorized	The system received a request from a user that is not authenticated.
403	Forbidden	The system received a request that the user is not authorized to make.
404	Not Found	The URL, entity, or account requested is not found in the system.
500	Internal Server Error	An unexpected condition was encountered.
503	Service Unavailable	The system is experiencing heavy load or another system failure.

Request¶

The following table shows the header parameters for the request:

Name	Type	Description
X-Auth-Token	String (Required)	A valid authentication token with administrative access. For details, see Get your credentials

Example Update alarm by ID: JSON request

{
    "criteria": "if (metric[\"average\"] < 100) { return new AlarmStatus(OK); } return new AlarmStatus(WARNING);"
}

Response¶

This operation does not return a response body.

Delete alarm by ID ¶

DELETE /entities/{entityId}/alarms/{alarmId}

Delete an alarm from your account.

The following table shows the possible response codes for this operation:

Response Code	Name	Description
200	OK	The request completed.
401	Unauthorized	The system received a request from a user that is not authenticated.
403	Forbidden	The system received a request that the user is not authorized to make.
404	Not Found	The URL, entity, or account requested is not found in the system.
500	Internal Server Error	An unexpected condition was encountered.
503	Service Unavailable	The system is experiencing heavy load or another system failure.

Request¶

The following table shows the header parameters for the request:

Name	Type	Description
X-Auth-Token	String (Required)	A valid authentication token with administrative access. For details, see Get your credentials

Note

This operation does not accept a request body.

Response¶

This operation does not return a response body.

Alarms¶

Create an alarm¶

Request¶

Response¶

Test an alarm¶

Request¶

Response¶

List alarms¶

Request¶

Response¶

Get alarm by ID¶

Request¶

Response¶

Update alarm by ID¶

Request¶

Response¶

Delete alarm by ID¶

Request¶

Response¶

Create an alarm ¶

Test an alarm ¶

List alarms ¶

Get alarm by ID ¶

Update alarm by ID ¶

Delete alarm by ID ¶