API Documentation | Alert

Representation of an Alert that occurred. Currently this endpoint will only return active (i.e. not cleared) alerts. Alerts are read only.

Fields

_cid string
The primary key
"/alert/4378611"
A string containing a alert cid
_acknowledgement string
The active acknowledgement for this alert, or null if none
"/acknowledgement/123"
A string containing an acknowledgement cid
_alert_url string
Link to this alert in the Circonus UI.
"https://example.circonus.com/fault-detection?alert_id=4378611"
A string containing a URL
_broker string
The broker on which the data is collected.
"/broker/1"
A string containing a broker cid
_check string
The check that this alert corresponds to.
"/check/62515"
A string containing a check cid
_check_name string
The name of the check as displayed in the Circonus UI.
"Ping test"
A string containing freeform text
_cleared_on number
When the alert cleared, if it has cleared
1382141605
A positive integer that contains the number of seconds since the UNIX epoch (midnight on January 1st, 1970 in Greenwich, United Kingdom)
_cleared_value string
If the alert cleared, the value that cleared all the rules.
"80.2"
A string containing freeform text
_maintenance array
A list of any active maintenance windows that pertain to this alert
["/maintenance/456"]
An array
string (zero or more times)

A string containing a maintenance cid
_metric_link string
A user defined link to external documentation for the metric that triggered this alert.
"http://example.com/docs/what_to_do_when/ping_fails.html"
A string containing a URL
_metric_name string
The name of the metric that triggered this alert.
"available"
A string containing freeform text
_metric_notes string
Documentation notes for the metric that triggered the alert.
"Simple Pinging"
A string containing freeform text
_occurred_on number
When this alert first occurred on
1382141546
A positive integer that contains the number of seconds since the UNIX epoch (midnight on January 1st, 1970 in Greenwich, United Kingdom)
_rule_set string
Rule set that contains the rules that triggered this alert.
"/rule_set/62515_available"
A string containing a rule_set cid
_severity number
The severity assigned to this alert by the rules in the ruleset
1
A number containing an integer between 0 and 5 inclusive
_tags array
The tags that were at the time assigned to the check bundle that triggered the alert. These serve as a historical record and cannot be altered by using either the API or GUI, nor can they be changed by altering the check bundles; Once the alert has been created they are immutable.
["datacenter:primary"]
An array of tags. The tags in the array are automatically sorted, deduplicated and transformed into their lowercase canonical form.
string (zero or more times)
An associated tag
A tag is just a string, with or without a colon, such as 'foo', 'bar', 'datacenter:london', or 'os:linux'. The part of the string before the colon is considered the category the tag is in; Tag strings without a colon will place the string in the 'uncategorized' category. Circonus will lowercase the contents of the string before storing it.
_value string
The value of the metric that triggered the alert.
"20.1"
A string containing freeform text

Example

Fetching Alerts

Fetching details for an alert is as simple as performing a GET on the alert cid:

GET /alert/4378611
{"_check_name":"Ping test","_cleared_on":1382141605,"_occurred_on":1382141546,"_value":"20.1","_tags":["datacenter:primary"],"_cid":"/alert/4378611","_broker":"/broker/1","_maintenance":["/maintenance/456"],"_alert_url":"https://example.circonus.com/fault-detection?alert_id=4378611","_metric_link":"http://example.com/docs/what_to_do_when/ping_fails.html","_metric_notes":"Simple Pinging","_cleared_value":"80.2","_severity":1,"_acknowledgement":"/acknowledgement/123","_check":"/check/62515","_metric_name":"available","_rule_set":"/rule_set/62515_available"}

From this we can see several interesting things:

Listing and Filtering Alerts

Alerts that have been cleared will not be listed via the API (though you can query the API directly for them via their cid as demonstrated above).

The simplest thing to do is to list all active alerts:

GET /alert
[{"_broker":"/broker/32","_tags":["datacenter:primary"],"_cid":"/alert/1234","_check_name":"resmon","_cleared_on":null,"_value":"0","_occurred_on":1704067200,"_metric_notes":null,"_severity":3,"_cleared_value":null,"_metric_name":"tuits`remaining","_check":"/check/654321","_acknowledgement":"/acknowledgement/1111","_rule_set":"/rule_set/654321_tuits`remaining","_maintenance":["/maintenance/123"],"_alert_url":"https://example.circonus.com/fault-detection?alert_id=1234","_metric_link":null},{"_broker":"/broker/32","_cid":"/alert/1235","_tags":["datacenter:primary"],"_check_name":"resmon","_value":"104212","_occurred_on":1706745600,"_cleared_on":null,"_metric_notes":null,"_cleared_value":null,"_severity":1,"_rule_set":"/rule_set/86534_splines`reticulating`queue","_metric_name":"splines`reticulating`queue","_check":"/check/86534","_acknowledgement":"/acknowledgement/2222","_maintenance":["/maintenance/123","/maintenance/456"],"_alert_url":"https://example.circonus.com/fault-detection?alert_id=1235","_metric_link":null},{"_severity":1,"_cleared_value":null,"_metric_notes":null,"_check":"/check/492727","_acknowledgement":null,"_metric_name":"droids`lookingfor","_rule_set":"/rule_set/492727_droids`lookingfor","_maintenance":[],"_alert_url":"https://example.circonus.com/fault-detection?alert_id=1300","_metric_link":null,"_cid":"/alert/1300","_tags":["datacenter:farfaraway"],"_broker":"/broker/32","_check_name":"resmon","_cleared_on":null,"_occurred_on":233366400,"_value":"C3PEO and R2D2"}]

You can also filter the search results by placing restrictions on the fields. For example, only severity 1 alerts:

Note on filtering, you should not use a filter without a search parameter as well, using just a filter may become unsupported in the future. Please see the section on API searching.

GET /alert?search=(check_name%3Aresmon)&f__severity=1
[{"_broker":"/broker/32","_tags":["datacenter:primary"],"_cid":"/alert/1235","_check_name":"resmon","_cleared_on":null,"_value":"104212","_occurred_on":1706745600,"_cleared_value":null,"_severity":1,"_metric_notes":null,"_metric_name":"splines`reticulating`queue","_check":"/check/86534","_acknowledgement":"/acknowledgement/2222","_rule_set":"/rule_set/86534_splines`reticulating`queue","_maintenance":["/maintenance/123","/maintenance/456"],"_alert_url":"https://example.circonus.com/fault-detection?alert_id=1235","_metric_link":null},{"_cleared_on":null,"_value":"C3PEO and R2D2","_occurred_on":233366400,"_check_name":"resmon","_broker":"/broker/32","_cid":"/alert/1300","_tags":["datacenter:farfaraway"],"_metric_link":null,"_alert_url":"https://example.circonus.com/fault-detection?alert_id=1300","_maintenance":[],"_metric_name":"droids`lookingfor","_check":"/check/492727","_acknowledgement":null,"_rule_set":"/rule_set/492727_droids`lookingfor","_severity":1,"_cleared_value":null,"_metric_notes":null}]

Or alerts that have been going on since before 2013:

GET /alert?search=(check_name%3Aresmon)&f__occurred_on_lt=1356998400
[{"_cid":"/alert/1300","_tags":["datacenter:farfaraway"],"_broker":"/broker/32","_check_name":"resmon","_cleared_on":null,"_occurred_on":233366400,"_value":"C3PEO and R2D2","_cleared_value":null,"_severity":1,"_metric_notes":null,"_check":"/check/492727","_acknowledgement":null,"_metric_name":"droids`lookingfor","_rule_set":"/rule_set/492727_droids`lookingfor","_maintenance":[],"_alert_url":"https://example.circonus.com/fault-detection?alert_id=1300","_metric_link":null}]

Or alerts that occurred on check bundles tagged for the primary data center

GET /alert?search=(check_name%3Aresmon)&f__tags_has=datacenter%3Aprimary
[{"_broker":"/broker/32","_tags":["datacenter:primary"],"_cid":"/alert/1234","_check_name":"resmon","_value":"0","_occurred_on":1704067200,"_cleared_on":null,"_metric_notes":null,"_severity":3,"_cleared_value":null,"_rule_set":"/rule_set/654321_tuits`remaining","_metric_name":"tuits`remaining","_acknowledgement":"/acknowledgement/1111","_check":"/check/654321","_metric_link":null,"_alert_url":"https://example.circonus.com/fault-detection?alert_id=1234"},{"_metric_name":"splines`reticulating`queue","_check":"/check/86534","_acknowledgement":"/acknowledgement/2222","_rule_set":"/rule_set/86534_splines`reticulating`queue","_cleared_value":null,"_severity":1,"_metric_notes":null,"_alert_url":"https://example.circonus.com/fault-detection?alert_id=1235","_metric_link":null,"_broker":"/broker/32","_cid":"/alert/1235","_tags":["datacenter:primary"],"_cleared_on":null,"_value":"104212","_occurred_on":1706745600,"_check_name":"resmon"}]

These (and any other field filters) can be combined and potentially all applied at the same time.

Modifying Alerts and Creating Alerts

It's not possible to directly modify or create new alerts with the API or Circonus GUI. You can only close an alert by either changing the external system that Circonus is checking or by altering the rules Circonus uses to determine what is alerting. Circonus does not offer a way to manually input historic or synthetic results into its system (you should consider using annotations instead).