Atom feed of this document
 
 
 

 4.8. Alarms

 4.8.1. Summary

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.

[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.

 4.8.2. Attributes

Table 4.10. 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

 4.8.3. Create Alarm

Verb URI Description
POST /entities/entityId/alarms Creates a new alarm for the specified entity. Specify the alarm's characteristics using a valid set of parameters from the table shown in the Attributes section above.

Normal Response Code: (201) 'Location' header contains a link to the newly created alarm.

Error Response Codes: 400, 401, 403, 500, 503

 

Example 4.46. Alarm Create Request: XML

<?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 4.47. Alarm Create Request: JSON

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


 4.8.4. Test Alarm

Verb URI Description
POST /entities/entityId/test-alarm Test run an alarm.

Normal Response Code: 200

Error Response Codes: 400, 401, 403, 413, 500, 503

 

Example 4.48. Test Alarm Request: XML

<?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 4.49. Test Alarm Request: JSON

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


 

Example 4.50. Test Alarm Response: XML

<?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 4.51. Test Alarm Response: JSON

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


 4.8.5. List Alarms

Verb URI Description
GET /entities/entityId/alarms List the alarms on the specified entity.

There are no parameters for this call.

Normal Response Code: 200

Error Response Codes: 401, 403, 500, 503

 

Example 4.52. List Alarms Response: XML

<?xml version="1.0" encoding="utf-8"?>
<container>
  <values>
    <alarm id="alAAAA">
      <check_id>chAAAA</check_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 4.53. List Alarms Response: JSON

{
    "values": [
        {
            "id": "alAAAA",
            "check_id": "chAAAA",
            "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
    }
}


 4.8.6. Get Alarm

Verb URI Description
GET /entities/entityId/alarms/alarmId Get information for a single alarm.

There are no parameters for this call.

Normal Response Code: 200

Error Response Codes: 401, 403, 500, 503

 

Example 4.54. Get Alarm Response: XML

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


 

Example 4.55. Get Alarm Response: JSON

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


 4.8.7. Update Alarm

Verb URI Description
PUT /entities/entityId/alarms/alarmId Update an alarm with the specified alarmId. Partial updates to an alarm are acceptable. You may specify only the parameters you would like to update.

Normal Response Code: (204) This code contains no content with an empty response body.

Error Response Codes: 400, 401, 403, 404, 500, 503

 

Example 4.56. Update Alarm Request: XML

Normal Response Code: (204) This operation does not contain a response body.

Error Response Code: 500

<?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 4.57. Alarm Update Request: JSON

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


 4.8.8. Delete Alarm

Verb URI Description
DELETE /entities/entityId/alarms/alarmId Delete an alarm from your account.

Normal Response Code: (204) This code contains no content with an empty response body.

Error Response Codes: 401, 403, 404, 500, 503



loading table of contents...