5.12. 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 DSL. For information about using the alarm language, refer to the reference documentation. For alarm examples by check, see Alarm examples.

[Note]Note

Criteria is optional. If you don't provide a criteria, the state of your alarm depends entirely on the success or failure of the check. This is a convenient shortcut for setting a simple alarm with a notification plan. For example, if you set a ping check on a server, it won't alert unless no pings are returned at all, whereas adding criteria would enable the alert to trigger if the ping round trip time went past a certain threshold.

Concept: Alarm and alert

Requirements: An entity, check, notification, and notification plan

Next step: View alarm notification history

Table 5.13. Attributes
NameDescriptionValidation
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 Disable processing and alerts on this alarm
  • Optional

  • Boolean

label A friendly label for an alarm.
  • Optional

  • String between 1 and 255 characters long

metadata Arbitrary key/value pairs.
  • Optional

  • Hash [String,String between 1 and 255 characters long:String,String between 1 and 255 characters long]

  • Array or object with number of items between 0 and 256

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

MethodURIDescription
POST/entities/{entityId}/alarms

Creates a new alarm for the specified entity.

POST/entities/{entityId}/test-alarm

Test an alarm before putting it in production.

GET/entities/{entityId}/alarms

List the alarms on the specified entityId.

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

Get information for a single alarm.

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

Updates the specified alarm with the properties submitted with the request.

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

Delete an alarm from your account.

 5.12.1. Create an alarm

 
MethodURIDescription
POST/entities/{entityId}/alarms

Creates a new alarm for the specified entity.

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

This table shows the possible response codes for this operation:

Response CodeNameDescription
201Accepted

'Location' header contains a link to the newly created alarm.

400Bad request

The system received an invalid value in a request.

401Unauthorized

The system received a request from a user that is not authenticated.

403Forbidden

The system received a request that the user is not authorized to make.

500Internal Server Error

An unexpected condition was encountered.

503Service Unavailable

The system is experiencing heavy load or another system failure.

 5.12.1.1. Request

This table shows the header parameters for the create an alarm request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

 

Example 5.81. XML request: Create an alarm

<?xml version="1.0" encoding="utf-8"?>
<alarm>
  <check_id>chAAAA</check_id>
  <criteria>if (metric["duration"] &gt;= 2) { return new AlarmStatus(OK); } return new AlarmStatus(CRITICAL);</criteria>
  <notification_plan_id>npAAAAA</notification_plan_id>
</alarm>

 

Example 5.82. JSON request: Create an alarm

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

 5.12.2. Test an alarm

 
MethodURIDescription
POST/entities/{entityId}/test-alarm

Test an alarm before putting it in production.

The test_alarm endpoint does not test individual alarms. Use it to post alarm criteria and alarm data in order to run the alarm test.

This table shows the possible response codes for this operation:

Response CodeNameDescription
200OK

The request completed.

400Bad request

The system received an invalid value in a request.

401Unauthorized

The system received a request from a user that is not authenticated.

403Forbidden

The system received a request that the user is not authorized to make.

500Internal Server Error

An unexpected condition was encountered.

503Service Unavailable

The system is experiencing heavy load or another system failure.

 5.12.2.1. Request

This table shows the header parameters for the test an alarm request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

 

Example 5.83. XML request: Test an alarm

<?xml version="1.0" encoding="utf-8"?>
<test_run_alarm>
  <criteria>if (metric["code"] == "404") { return new AlarmStatus(CRITICAL, "not found"); } return new AlarmStatus(OK);</criteria>
  <checks_data>
    <check_data>
      <timestamp>1319222001982</timestamp>
      <monitoring_zone_id>mzxJ4L2IU</monitoring_zone_id>
      <available>true</available>
      <status>code=200,rt=0.257s,bytes=0</status>
      <metrics>
        <bytes>
          <type>i</type>
          <data>0</data>
        </bytes>
        <tt_firstbyte>
          <type>I</type>
          <data>257</data>
        </tt_firstbyte>
        <tt_connect>
          <type>I</type>
          <data>128</data>
        </tt_connect>
        <code>
          <type>s</type>
          <data>200</data>
        </code>
        <duration>
          <type>I</type>
          <data>257</data>
        </duration>
      </metrics>
    </check_data>
  </checks_data>
</test_run_alarm>

 

Example 5.84. JSON request: Test an alarm

{
    "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"
                }
            }
        }
    ]
}

 5.12.2.2. Response

 

Example 5.85. XML response: Test an alarm

<?xml version="1.0" encoding="utf-8"?>
<alarm_data>
  <alarm_data>
    <timestamp>1319224500831</timestamp>
    <state>OK</state>
    <status>Matched default return statement</status>
  </alarm_data>
</alarm_data>

 

Example 5.86. JSON response: Test an alarm

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

 5.12.3. List alarms

 
MethodURIDescription
GET/entities/{entityId}/alarms

List the alarms on the specified entityId.

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

This table shows the possible response codes for this operation:

Response CodeNameDescription
200OK

The request completed.

401Unauthorized

The system received a request from a user that is not authenticated.

403Forbidden

The system received a request that the user is not authorized to make.

500Internal Server Error

An unexpected condition was encountered.

503Service Unavailable

The system is experiencing heavy load or another system failure.

 5.12.3.1. Request

This table shows the header parameters for the list alarms request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

This operation does not accept a request body.

 5.12.3.2. Response

 

Example 5.87. XML response: List Alarms

<?xml version="1.0" encoding="utf-8"?>
<container>
  <values>
    <alarm id="alAAAA">
      <check_id>chAAAA</check_id>
      <entity_id>enZZZZA</entity_id>
      <criteria>if (metric["duration"] &gt;= 2) { return new AlarmStatus(OK); } return new AlarmStatus(CRITICAL);</criteria>
    </alarm>
  </values>
  <metadata>
    <count>1</count>
    <limit>50</limit>
    <marker/>
    <next_marker/>
    <next_href/>
  </metadata>
</container>

 

Example 5.88. JSON response: List Alarms

{
    "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
    }
}

 5.12.4. Get alarm by ID

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

Get information for a single alarm.

This table shows the possible response codes for this operation:

Response CodeNameDescription
200OK

The request completed.

401Unauthorized

The system received a request from a user that is not authenticated.

403Forbidden

The system received a request that the user is not authorized to make.

500Internal Server Error

An unexpected condition was encountered.

503Service Unavailable

The system is experiencing heavy load or another system failure.

 5.12.4.1. Request

This table shows the header parameters for the get alarm by id request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

This operation does not accept a request body.

 5.12.4.2. Response

 

Example 5.89. XML response: Get alarms by ID

<?xml version="1.0" encoding="utf-8"?>
<alarm id="alAAAA">
  <check_id>chAAAA</check_id>
  <entity_id>enZZZZA</entity_id>
  <criteria>if (metric["duration"] &gt;= 2) { return new AlarmStatus(OK); } return new AlarmStatus(CRITICAL);</criteria>
</alarm>

 

Example 5.90. JSON response: Get alarms by ID

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

 5.12.5. Update alarm by ID

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

Updates the specified alarm with the properties submitted with the request.

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

This table shows the possible response codes for this operation:

Response CodeNameDescription
204No Content

The server has fulfilled the request but does not need to return an entity-body.

400Bad request

The system received an invalid value in a request.

401Unauthorized

The system received a request from a user that is not authenticated.

403Forbidden

The system received a request that the user is not authorized to make.

404Not Found

The URL or entity requested is not found in the system.

500Internal Server Error

An unexpected condition was encountered.

503Service Unavailable

The system is experiencing heavy load or another system failure.

 5.12.5.1. Request

This table shows the header parameters for the update alarm by id request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

 

Example 5.91. XML request: Update alarm by ID

<?xml version="1.0" encoding="utf-8"?>
<alarm>
  <criteria>if (metric["average"] &lt; 100) { return new AlarmStatus(OK); } return new AlarmStatus(WARNING);</criteria>
</alarm>

 

Example 5.92. JSON request: Update alarm by ID

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

 5.12.6. Delete alarm by ID

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

Delete an alarm from your account.

This table shows the possible response codes for this operation:

Response CodeNameDescription
200OK

The request completed.

401Unauthorized

The system received a request from a user that is not authenticated.

403Forbidden

The system received a request that the user is not authorized to make.

404Not Found

The URL or entity requested is not found in the system.

500Internal Server Error

An unexpected condition was encountered.

503Service Unavailable

The system is experiencing heavy load or another system failure.

 5.12.6.1. Request

This table shows the header parameters for the delete alarm by id request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access.

This operation does not accept a request body.



loading table of contents...