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]](/cm-v1.0-cm-devguide/common/images/admon/note.png) | 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. |
| Name | Description | Validation |
| check_id | The ID of the check to alert on. |
|
| notification_plan_id | The id of the notification plan to execute when the state changes. |
|
| criteria | The alarm DSL for describing alerting conditions and their output states. |
|
| disabled | Disable processing and alerts on this alarm |
|
| label | A friendly label for an alarm. |
|
| metadata | Arbitrary key/value pairs. |
|
| 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"] >= 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"
}
| 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"
}
]
| 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"] >= 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
}
}
| 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"] >= 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);"
}
| 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"] < 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);"
}
