API Documentation | Check Bundle

Check bundles are what you configure to get your data into the system. A bundle is a collection of checks that have the same configuration and target, but collect from different brokers. A bundle can have one check or many checks in it, changing the bundle effects all the associated checks. The individual checks in the bundle have their own unique IDs which are typically required for setting up items such as graphs or rule sets.

Fields

_cid string
The primary key
"/check_bundle/45315"
A string containing a check_bundle cid
_check_uuids array
The check uuids for the checks that make up this check bundle.
["36b5a748-5614-57f1-87e3-32ca709c9cac","25b5a748-5614-44f1-87e3-32ca709c9c45","bd9d597f-a1dd-46af-9219-509b12909abc"]
An array
string (zero or more times)
An individual _check_uuid
A string containing freeform text
_checks array
The checks that make up this check bundle. Circonus automatically creates a corresponding check for each broker
["/check/62513","/check/62514","/check/62515"]
An array
string (zero or more times)
An individual check
A string containing a check cid
_created number
The point in time when this object was created
1372178325
A positive integer that contains the number of seconds since the UNIX epoch (midnight on January 1st, 1970 in Greenwich, United Kingdom)
_last_modified number
The point in time when this object was last updated.
1372178330
A positive integer that contains the number of seconds since the UNIX epoch (midnight on January 1st, 1970 in Greenwich, United Kingdom)
_last_modified_by string
The object id of the last user to modify this object.
"/user/923"
A string containing a user cid
_reverse_connection_urls array
Experimental reverse client connection URLs. Subject to change
An array
string (zero or more times)
Experimental reverse client connection URL. Subject to change
A string containing freeform text
brokers array
The brokers that are responsible for gathering the metrics. These can either be Circonus brokers running in the cloud or enterprise brokers running in your datacenter. A corresponding check will automatically be created for each broker. Note: When removing a broker from the array, which means removing a check from a check bundle, you have the option of removing any RuleSets associated with that check. To do so, simply add the query parameter ?remove_rules=1 to your request. See further details in 'Adding and Removing Brokers/Checks from a Check Bundle' below.
["/broker/2","/broker/1","/broker/32"]
An array. Required.
string (zero or more times)
A broker
A string containing a broker cid
config object
The configuration of the checks.
{"avail_needed":"100","count":"5","interval":"2000"}
An object. The keys and values are dependent on the check type (HTTP, DNS, JSON, etc.). You can refer to the specific type definitions to find the valid parameters and their accepted values.
display_name string
The name of the check that will be displayed in the web interface.
"Ping home router"
A string containing freeform text
metric_filters array
An array of one or more rules to 'allow' or 'deny' metrics whose names match the regular expression. See 'Metric Filters' below for more detail.
[["deny","datacenter_.+,VA",""],["allow",".","default rule"]]
An array
array (zero or more times)

An array
string
Action for this rule.
A string containing either 'allow' or 'deny'
string
A Perl-compatible regular expression that specifies a pattern for metric name(s) that should be matched by this rule.
See 'Metric Filters' below.
string
Comment
A string containing freeform text
metric_limit number
Setting a metric limit will tell the Circonus backend to periodically look at the check to see if there are additional metrics the broker has seen that we should collect. It will not reactivate metrics you had previously collected and then marked as inactive. Values are 0 to disable, -1 to enable all metrics or 1+ to collect up to that value (both -1 and 1+ can not exceed other account restrictions).
A number containing an integer, positive or negative
metrics array
Details on the metrics each check in this bundle gathers. If the query_broker=1 query parameter is passed this list will also include any additional metrics that are available for collection but are not currently active.
[{"type":"numeric","status":"active","units":"seconds","name":"average","tags":[]},{"type":"numeric","status":"active","units":"seconds","name":"maximum","tags":[]},{"type":"numeric","tags":[],"name":"minimum","units":"seconds","status":"active"}]
An array
object (zero or more times)
Details on a single metric that is/can be collected.
An object
name string
The name of the metric
A string containing freeform text
type string
The type of the metric.
A string containing either 'numeric', 'text', 'histogram', 'composite', or 'caql'
status string
If the metric is 'active' (currently being collected) or merely 'available' (can be collected but isn't right now)
A string containing either 'active' or 'available'
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.
units string
The unit of measurement the metric represents (e.g., bytes, seconds, milliseconds).
A string containing freeform text
notes string
Notes about this bundle
"Pinging the dynamic dns name for my home router"
A string containing freeform text
period number
The period between each time the check is made.
60
A number containing a floating point number representing seconds and fractions of seconds. Must be at least 10 seconds. Must be at most 300 seconds.Optional, defaults to sixty seconds.
status string
If the check is activate or disabled.
"active"
A string containing either 'active' or 'disabled'. Optional. New check bundles will always be active by default.
tags array
["datacenter:home"]
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.
target string
A string that is the hostname the check will contact to retrieve metrics, or the host that will be sending metrics to this check. For example: if you wanted to ping myhomecomputer.no-ip.biz, the target would be as follows:
"myhomecomputer.no-ip.biz"
A string containing freeform text
timeout number
The length of time in seconds before the check will timeout if no response is returned to the broker.
10
A number containing a floating point number representing seconds and fractions of seconds. Must be at most 300 seconds.Optional, defaults to 10 seconds.
type string
The type of check that this is. This has no default value and must be supplied for each check.
"ping_icmp"
A string containing one of 'caql', 'cim', 'circonuswindowsagent', 'circonuswindowsagent:nad', 'collectd', 'composite', 'consul', 'dcm', 'dhcp', 'dns', 'elasticsearch', 'external', 'ganglia', 'googleanalytics', 'haproxy', 'http', 'http:apache', 'httptrap', 'imap', 'jmx', 'json', 'json:couchdb', 'json:mongodb', 'json:nad', 'json:riak', 'ldap', 'memcached', 'munin', 'mysql', 'newrelic_rpm', 'nginx', 'nrpe', 'ntp', 'oracle', 'ping_icmp', 'pop3', 'postgres', 'redis', 'resmon', 'smtp', 'snmp', 'snmp:momentum', 'sqlserver', 'ssh2', 'statsd', 'tcp', 'varnish', 'cloudwatch', 'ec_console', 'mongodb', 'promtext', 'prometheus', or 'graphite_tls'

Example

Fetching Check Bundles

Fetching a check bundle is as simple as performing a GET on the check bundle's cid:

GET /check_bundle/45315
{"type":"ping_icmp","config":{"interval":"2000","count":"5","avail_needed":"100"},"_created":1372178325,"status":"active","_check_uuids":["36b5a748-5614-57f1-87e3-32ca709c9cac","25b5a748-5614-44f1-87e3-32ca709c9c45","bd9d597f-a1dd-46af-9219-509b12909abc"],"metric_filters":[],"_last_modified":1372178330,"_checks":["/check/62513","/check/62514","/check/62515"],"tags":["datacenter:home"],"_cid":"/check_bundle/45315","timeout":10,"metrics":[{"type":"numeric","name":"average","tags":[],"units":"seconds","status":"active"},{"type":"numeric","status":"active","units":"seconds","tags":[],"name":"maximum"},{"type":"numeric","name":"minimum","tags":[],"status":"active","units":"seconds"}],"brokers":["/broker/2","/broker/1","/broker/32"],"_last_modified_by":"/user/923","display_name":"Ping home router","target":"myhomemachine.no-ip.biz","period":60,"notes":"Pinging the dynamic dns name for my home router"}

We can see several interesting things:

Creating Check Bundles

Creating a new check bundle is as simple as making a HTTP POST request to /check_bundle and passing JSON representing the new annotation:

POST /check_bundle
{"metrics":[{"name":"Honeydew`detectors`0`count","tags":[],"status":"active","units":"seconds","type":"numeric"}],"brokers":["/broker/1"],"period":120,"notes":"Using the infamous http://muppet.wikia.com/wiki/Gorilla_Detector","target":"example.com","display_name":"Number of Gorillas","tags":["datacenter:studio"],"type":"json","status":"active","timeout":10,"config":{"url":"http://example.com/data/muppet.json","port":"80"}}

(In the above example we configure Circonus to poll a URL that returns a JSON document every two minutes.)

Configuring The Type of Check

The two key fields "type" and "config" define what kind of check will be run and how that check is configured respectively. Each different type of check has its own config parameters that must be included.

New Bundle Deduplication

During the creation process, new POST requests are deduplicated against existing bundles. The criteria for considering a bundle duplicate is that is has the same target, brokers, type, and config as an existing bundle. Note that name is not considered when comparing bundles.

If a duplicate bundle is found, the existing bundle will be returned to your request unaltered. It is up to the client to make sure it is correct. To alter the bundle you must issue a PUT to the appropriate cid.

Two query string parameters can alter deduplication behavior:

Setting Which Metrics To Be Stored

The metrics field contains an array which contains a list of all the types of data we are going to store in Circonus. These are normally populated by each broker executing each check with things it determined during that execution. For example a "http" check will make a HTTP request, and you can then configure metrics to record various things about that request such as the time to the first byte, the number of bytes received in total, the total request duration, the HTTP response code, etc.

The "name" property determines what of the things discovered in the execution of the check by the broker this metric will store. For the simpler check bundle types like "http" these are a known list like "tt_firstbyte", "bytes", etc. For other types of metrics where user data is returned this can be more freeform.

For example, for a JSON check the name provides a path to the data element in the JSON that Circonus should store. In the above check we created, the http://example.com/data/muppet.json URL must return something that looks something like:

{
    "Honeydew": {
        "detectors" : [
            {
                "count": 6,
                …
            },
            …
        ],
        …
    },
    …
}

The "Honeydew`detectors`0`count" provides a path through this data structure deliminated with the backtick (`): The object under the "Honeydew" key, the "detectors" key under that, the 0th (first) element of the array under that, and the "numeric" value stored under the "count" key in that object.

The metric's "type" property can have three values:

numeric
A numerical value that can be represented by a line on a graph. This is the most common type of metric, and is used to store things like percentages, bytes, durations, counts, etc. Essentially anything that can be distilled down to a number and can be compared as greater or equal to other numeric values.
text
Text values of things that cannot be directly compared. Some values like HTTP response codes are made up of digits but should be treated textually (e.g. you can't compare HTTP codes numerically - a 404 isn't 'greater' than a 200 response).
histogram
A metric that accepts multiple numeric values for a given time period. This type of metric is normally populated via data being pushed at Circonus via HTTPTrap or the collectd compatible interface rather than by Circonus' brokers polling for data.

In some situations a broker can determine what additional metrics are available to be collected for a check. You can query this by passing the query_broker=1 parameter when you get a cid:

GET /check_bundle/3374?query_broker=1
{"_cid":"/check_bundle/3374","timeout":10,"metrics":[{"tags":[],"name":"bytes","units":"bytes","status":"active","type":"numeric"},{"type":"text","name":"code","tags":[],"units":null,"status":"active"},{"tags":[],"name":"duration","status":"active","units":"milliseconds","type":"histogram"},{"type":"numeric","units":null,"status":"available","name":"truncated","tags":[]},{"type":"histogram","status":"active","units":"milliseconds","tags":[],"name":"tt_connect"},{"type":"numeric","name":"tt_firstbyte","tags":[],"units":"milliseconds","status":"available"}],"brokers":["/broker/1"],"period":60,"notes":null,"target":"www.example.com","_last_modified_by":"/user/166","display_name":"www.example.com http","type":"http","_created":1376405704,"status":"active","_check_uuids":["129d597f-abdd-9aaf-9219-509b12909ac1"],"config":{"redirects":"0","header_Host":"example.com","http_version":"1.1","code":"^200$","url":"http://www.example.com","method":"GET","read_limit":"1048576"},"metric_filters":[],"_last_modified":1381514352,"tags":[],"_checks":["/check/4373"]}

The metrics that the broker knows about that aren't "active" are listed as "available", in this case "tt_firstbyte" and "truncated".

Metric Filters

Instead of specifying which metrics you want to collect, you can specify patterns to collect or not with allow/deny regular expression rules. Do this by including the metric_filters field as an array of one or more rules, which are arrays with the allow/deny type, a Perl-compatible regular expression, and comment:

PUT /check_bundle/17523
{"metric_filters":[["deny","do_not_collect",""],["deny","^reject.+this$",""],["allow",".","default"]]}

This example tells the broker you want to collect all metrics EXCEPT those which:

Metric filters will be applied at the broker in the order you specified them, so if you have a metric name of "reject_do_not_collect_this", the first regex will filter the metric, and the second regex will not be tested against it. It is generally better to arrange your filter_rule regexes so that the most broadly applicable ones are earlier in the list than the more narrowly applicable ones.

Regex Limitations

The following are the characteristics and limitations for metric filter_rule regular expressions (PCRE):

Effect of Metric Filters on your Account's Metric Limit

Because check bundles with metric_filters can allow through an indeterminate number of metrics, Circonus gives you leeway with regard to the number of metrics purchased for your account:

When using metric filters (with push-type checks which may be set to collect every metric encountered) Circonus will allow collection of metrics up to 25% over your account's metric limit for each check through the end of the billing period. At the end of the billing period, Circonus will adjust your metric limit according to the number of metrics you are collecting and the next cycle will allow you to collect 25% above that, and so on.

This allows you to push a large amount of data to Circonus without hitting your metric limit and potentially losing data until you are able to manually raise the limit. At the same time, it applies a reasonable brake on the number of metrics collected, in order to avoid an unintended deluge of metrics and larger than expected billing fees. Your sales manager at Circonus can raise or lower this limit at your request.

Changing The Type of a Metric

In rare occasions you may want to change the type of a metric. For example, you may realize that even though a value has all digits it should be treated as text instead of numeric. A concrete example of this is HTTP response codes: even though they are made of digits, they shouldn't be treated as numbers; e.g., there is no such thing as the "average mean" status code).

Changing the type of a metric has ramifications for previously collected data and for alerting. Because of this, we require that if you are changing the type of a metric you explicitly pass one or more set_metric_type parameters listing each metric you're allowing changes for.

PUT /check_bundle/17523?set_metric_type=code
{"metrics":[{"type":"text","name":"code"}]}

Be aware that changing the type of a metric will remove all rules associated with that metric (effectively meaning alerting for that metric is disabled until you add new rules to the system).

Adding and Removing Brokers/Checks from a Check Bundle

Each broker listed in the brokers array represents one Check, assigned to that broker. You can have as many brokers/checks in a check bundle as you wish. Removing all brokers deactivates the check bundle. To add additional broker(s) to a bundle, perform a PUT to the check bundle cid, updating the brokers field as appropriate:

PUT /check_bundle/17523
{"brokers":["/broker/1","/broker/2","/broker/3"]}

To remove a check from the bundle, simply remove the associated broker from the array.

When removing a broker/check, you have the option of also removing any Rules associated with that check. Simply add ?remove_rules=1 to the query parameter when sending your request and all Rules associated with removed brokers/checks will also be removed:

PUT /check_bundle/17523?remove_rules=1
{"brokers":["/broker/1"]}

Note: If any rules that you remove are members of one or more Ruleset Groups, you will receive a response header:

X-Circonus-RuleSetGroupsModified

containing a comma-separated list of ruleset group ids affected. If you receive this response header, you should review those Ruleset Groups to make sure your formulas will still generate alerts when you want them to.

Listing and Filtering for Check Bundles

All active check bundles for the account can be listed simply by performing a HTTP GET request on /check_bundle (disabled check bundles are not listed). You can apply filters in the usual way; for example, to list all check bundles that are on a particular broker:

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 /check_bundle?f_broker_has=/broker/342
[{"metric_filters":[],"_last_modified":1356639352,"_checks":["/check/4017"],"tags":[],"type":"tcp","_created":1356039459,"_check_uuids":["224d597f-a12d-16af-3219-409b139092bc"],"status":"active","config":{"port":"6667","use_ssl":"false"},"metrics":[{"status":"active","units":"milliseconds","tags":[],"name":"tt_connect","type":"numeric"}],"brokers":["/broker/342"],"period":60,"notes":null,"display_name":"Check we can TCP connect to the IRC port","_last_modified_by":"/user/166","target":"irc.example.com","timeout":10,"_cid":"/check_bundle/3083"}]

Or the check bundle that has a particular check in it:

GET /check_bundle?f__checks_has=/check/994
[{"timeout":10,"_cid":"/check_bundle/470","brokers":["/broker/1"],"metrics":[{"type":"numeric","status":"active","units":null,"tags":[],"name":"get_hits"},{"type":"text","name":"version","status":"active"}],"display_name":"Memcached check","_last_modified_by":"/user/169","target":"mc1.memcachedcluster.example.com","notes":null,"period":60,"type":"memcached","config":{"port":"11211"},"status":"active","_check_uuids":["bb2d597f-11dc-16af-7c19-509b129092bb"],"_created":1285614902,"metric_filters":[],"tags":[],"_checks":["/check/994"],"_last_modified":1285614907}]

To list all check bundles of a given type, like dns you will want to use a search:

GET /check_bundle?search=(type%3Adns)
[{"_last_modified":1372178673,"tags":["datacenter:home"],"_checks":["/check/62516"],"metric_filters":[],"config":{"rtype":"A","ctype":"IN","query":"myhomemachine.no-ip.biz"},"_created":1372178673,"_check_uuids":["134d597f-dadd-a2af-9219-509b12909bba"],"status":"active","type":"dns","_last_modified_by":"/user/923","display_name":"nf1.no-ip.com dns","target":"nf1.no-ip.com","period":60,"notes":"Log what IP address my home router DNS points to","metrics":[{"type":"text","tags":[],"name":"answer","units":null,"status":"active"}],"brokers":["/broker/1"],"_cid":"/check_bundle/45316","timeout":10}]

Or the check bundles that target a particular server:

GET /check_bundle?search=(host%3Aadmin.example.com)
[{"config":{"method_crypt_cs":"aes128-ctr","method_comp_sc":"none","method_crypt_sc":"aes128-ctr","method_comp_cs":"none","port":"22","method_hostkey":"ssh-dss"},"status":"active","_check_uuids":["a19d597f-a1dd-56af-9219-509b1290923a"],"_created":1334245843,"type":"ssh2","tags":["datacenter:primary"],"_checks":["/check/11643"],"_last_modified":1334245843,"metric_filters":[],"_cid":"/check_bundle/9548","timeout":10,"display_name":"SSH on the Admin Server","_last_modified_by":"/user/923","target":"admin.example.com","notes":null,"period":60,"brokers":["/broker/1"],"metrics":[{"type":"numeric","name":"duration","tags":[],"units":"milliseconds","status":"active"}]}]

Or the check bundle with a particular name:

GET /check_bundle?search=Test%20Webserver
[{"type":"http","_created":1334244931,"_check_uuids":["129d597f-a1dd-7caf-9219-509b1290922d"],"status":"active","config":{"redirects":"0","header_Host":"www.example.com","body":"Example Homepage","code":"^200$","url":"http://www.example.com","method":"GET"},"metric_filters":[],"_last_modified":1334244932,"tags":[],"_checks":["/check/11642"],"timeout":10,"_cid":"/check_bundle/9547","metrics":[{"type":"numeric","name":"duration","tags":[],"status":"active","units":"milliseconds"},{"type":"numeric","units":"bytes","status":"active","tags":[],"name":"bytes"},{"type":"numeric","status":"active","units":"milliseconds","tags":[],"name":"tt_firstbyte"},{"type":"numeric","status":"active","units":"milliseconds","name":"tt_connect","tags":[]},{"type":"text","tags":[],"name":"body_match","units":null,"status":"active"},{"tags":[],"name":"code","units":null,"status":"active","type":"text"},{"tags":[],"name":"truncated","status":"active","units":null,"type":"numeric"}],"brokers":["/broker/32"],"period":60,"notes":null,"target":"www.example.com","_last_modified_by":"/user/923","display_name":"Test Webserver"}]

Or the check bundles with a particular tag:

GET /check_bundle?search=(tags%3Adatacenter:studio)
[{"display_name":"Number of Gorillas","_last_modified_by":"/user/923","target":"example.com","notes":"Using the infamous http://muppet.wikia.com/wiki/Gorilla_Detector","period":120,"brokers":["/broker/1"],"metrics":[{"name":"Honeydew`detectors`0`count","tags":[],"status":"active","units":null,"type":"numeric"}],"timeout":10,"_cid":"/check_bundle/56875","tags":["datacenter:studio"],"_checks":["/check/77018"],"_last_modified":1383862842,"metric_filters":[],"config":{"port":"80","url":"http://example.com/data/muppet.json"},"status":"active","_check_uuids":["239d597f-bcdd-46af-8c19-509b12909221"],"_created":1383862366,"type":"json"}]

Removing Check Bundles

You cannot completely remove check bundles from the system (the details of the check bundle will always be accessible by performing a GET on the check bundle's cid). However, you can hide the check bundle from the web interface and from API listings by performing a DELETE request on the check bundle cid:

DELETE /check_bundle/7239174

Doing this will also set the check bundle's status to "disabled".