API Documentation | Rule Set Group

Rule Set Groups allow you to group together rule sets and trigger alerts based on combinations of those rule sets faulting; for example, triggering a further alert if a certain number of the rule sets themselves are faulting or if an explicit combination of the rulesets are in a specific fault state.

Fields

_cid string
The primary key
"/rule_set_group/1234"
A string containing a rule_set_group cid
contact_groups object
The contact groups to contact at each severity if this rule set group is alerting
{"1":["/contact_group/426","/contact_group/427"],"4":[],"5":[],"3":[],"2":["/contact_group/426"]}
An object
1 array
A list of contact groups to contact when this rule set group is alerting at severity 1
An array
string (zero or more times)
A contact group to contact
A string containing a contact_group cid
2 array
A list of contact groups to contact when this rule set group is alerting at severity 2
An array
string (zero or more times)
A contact group to contact
A string containing a contact_group cid
3 array
A list of contact groups to contact when this rule set group is alerting at severity 3
An array
string (zero or more times)
A contact group to contact
A string containing a contact_group cid
4 array
A list of contact groups to contact when this rule set group is alerting at severity 4
An array
string (zero or more times)
A contact group to contact
A string containing a contact_group cid
5 array
A list of contact groups to contact when this rule set group is alerting at severity 5
An array
string (zero or more times)
A contact group to contact
A string containing a contact_group cid
formulas array
What combination of rule set conditions described in the rule_set_conditions field must be met in order for this rule set group to raise an alert.
[{"expression":"(A and B) and not C","wait":0,"raise_severity":2},{"raise_severity":1,"expression":3,"wait":5}]
An array. Order matters; Each formula will be evaluated in turn and the first matching one will raise the speficied severity alert.
object (one or more times)
An expression that can be matched and the corrisponding severity that will be raised
An object
expression string
An expression that describes the combination of conditions in rule_set_conditions that must be met for this rule set group to itself generate an alert.
A string containing an expression. The expression has two possible forms. The first of these, an integer number, indicates a simple threshold - an alert will fire if at least this many of the rule_set_conditions are met. The second, more complex form, allows you to specify an exact combination of the rule_set_conditions with lowercase "and", "or", "not" and brackets and uppercase letters "A", "B", "C", etc corresponding to the respective first, second, third, etc rule_set_conditions.
raise_severity number
The severity alert that will be raised if the expression matches
A number containing an integer between 0 and 5 inclusive
wait number
The number of minutes to wait before contacting configured groups about this alert
A number containing an integer greater than or equal to zero
name string
The name of the rule set group. Required.
"Multiple webservers gone bad"
A string containing freeform text
rule_set_conditions array
The conditions that are evaluated as part of this group, i.e. the rule sets and severities that the expressions in the formula field will be evaluated against to determine if this rule set group should raise an alert itself.
[{"rule_set":"/rule_set/11641_tt_firstbyte","matching_severities":["1","2"]},{"rule_set":"/rule_set/11642_tt_firstbyte","matching_severities":["1","2"]},{"matching_severities":["1","2"],"rule_set":"/rule_set/11643_tt_firstbyte"}]
An array. The order of the conditions is important in so much that the first condition will be condition 'A' in complex expressions, the second will be 'B', the third 'C' and so on.
object (one or more times)
An individual condition made up of a rule set and possible severities it must be alerting at.
An object
matching_severities array or string
The possible severities that the rule set must be alerting at in order for this condition to be met
An unordered array containing numbers, each number being an integer between 1 and 5 inclusive, with no number being repeated. For convenience you may also pass in a string containing a CSV format string of these numbers (e.g. "1,2,3") - however, the field will always return an array object.
number (zero or more times)
An associated severity
A number containing an integer between 0 and 5 inclusive
rule_set string
The rule set that must be generating an alert for the condition to be met
a string containing a rule_set cid, for example '/rule_set/12345
tags array

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.

Example

Fetching a Rule Set

Fetching details for an rule set group is as simple as performing a GET on the rule set cid:

GET /rule_set_group/1234
{"contact_groups":{"1":["/contact_group/426","/contact_group/427"],"4":[],"5":[],"3":[],"2":["/contact_group/426"]},"rule_set_conditions":[{"matching_severities":["1","2"],"rule_set":"/rule_set/11641_tt_firstbyte"},{"matching_severities":["1","2"],"rule_set":"/rule_set/11642_tt_firstbyte"},{"rule_set":"/rule_set/11643_tt_firstbyte","matching_severities":["1","2"]}],"formulas":[{"wait":0,"expression":"(A and B) and not C","raise_severity":2},{"raise_severity":1,"expression":3,"wait":5}],"name":"Multiple webservers gone bad","_cid":"/rule_set_group/1234"}

From this we can see some important things:

Creating a New Rule Set Group

Creating a new rule set group is as simple as making a HTTP POST request to /rule_set_group and passing JSON representing the new rule set group:

POST /rule_set_group
{"rule_set_conditions":[{"matching_severities":["1"],"rule_set":"/rule_set/17277_volume_alpha`free"},{"rule_set":"/rule_set/17277_volume_beta`free","matching_severities":["1"]},{"rule_set":"/rule_set/17277_volume_gamma`free","matching_severities":["1"]}],"contact_groups":{"2":[],"3":[],"4":[],"1":["/contact_group/426"],"5":[]},"formulas":[{"raise_severity":1,"expression":2,"wait":3}],"name":"Panic When Only One Drive Has Free Space"}

As is usual, the POST request returns the full JSON in the response (including the new rule set group's cid

Updating a Rule Set Group

Rule set groups can be updated simply by using the PUT HTTP method with new field values:

PUT /rule_set_group/3141
{"formulas":[{"raise_severity":1,"wait":0,"expression":3},{"raise_severity":2,"wait":4,"expression":2}],"contact_groups":{"3":[],"2":["/contact_group/426"],"5":[],"4":[],"1":["/contact_group/426","/contact_group/427"]}}

As is normal with Circonus the PUT method returns the full JSON of the updated rule set group in response.

Note in the above example we need to be careful about the order in which specify the formulas. Formulas are evaluated in the order they are listed which can lead to some unexpected results if this is not borne in mind. For example, if the order of the formulas were reversed in the above example then a severity 1 alert could never be raised because the expression 2 (i.e. "two or more") would always match when 3 (i.e. "three or more") would, meaning evaluation would be stopped at that point and a severity 2 alert would be raised instead

Listing and Searching Rule Set Groups

You can list all rule set groups for your account simply by requesting the /rule_set_group path with a simple GET request.

GET /rule_set_group
[{"formulas":[{"raise_severity":2,"expression":"(A and B) and not C","wait":0},{"wait":5,"expression":3,"raise_severity":1}],"name":"Multiple webservers gone bad","_cid":"/rule_set_group/1234","contact_groups":{"3":[],"2":["/contact_group/426"],"5":[],"4":[],"1":["/contact_group/426","/contact_group/427"]},"rule_set_conditions":[{"rule_set":"/rule_set/11641_tt_firstbyte","matching_severities":["1","2"]},{"matching_severities":["1","2"],"rule_set":"/rule_set/11642_tt_firstbyte"},{"matching_severities":["1","2"],"rule_set":"/rule_set/11643_tt_firstbyte"}]},{"rule_set_conditions":[{"matching_severities":["1"],"rule_set":"/rule_set/17277_volume_alpha`free"},{"matching_severities":["1"],"rule_set":"/rule_set/17277_volume_beta`free"},{"matching_severities":["1"],"rule_set":"/rule_set/17277_volume_gamma`free"}],"contact_groups":{"2":["/contact_group/426"],"3":[],"1":["/contact_group/426","/contact_group/427"],"4":[],"5":[]},"_cid":"/rule_set_group/3141","formulas":[{"expression":3,"wait":0,"raise_severity":1},{"raise_severity":2,"wait":4,"expression":2}],"name":"Panic When Only One Drive Has Free Space"}]

By searching, you can restrict which rule set groups are returned. For example, you can list only those rule sets that have "webservers" in their titles:

GET /rule_set_group?search=*webservers*
[{"name":"Multiple webservers gone bad","formulas":[{"raise_severity":2,"wait":0,"expression":"(A and B) and not C"},{"raise_severity":1,"wait":5,"expression":3}],"_cid":"/rule_set_group/1234","contact_groups":{"1":["/contact_group/426","/contact_group/427"],"4":[],"5":[],"2":["/contact_group/426"],"3":[]},"rule_set_conditions":[{"matching_severities":["1","2"],"rule_set":"/rule_set/11641_tt_firstbyte"},{"rule_set":"/rule_set/11642_tt_firstbyte","matching_severities":["1","2"]},{"matching_severities":["1","2"],"rule_set":"/rule_set/11643_tt_firstbyte"}]}]

Removing Rule Set Groups

Rule set groups can be simply removed by using the DELETE HTTP method on the cid:

DELETE /rule_set_group/3141