API Documentation | Template

Templates are now deprecated in favor of the richer Check and CheckBundle API endpoints.

Templates are a means to setup a mass number of checks quickly through both the API and UI. A master host and check bundles are items already being collected by the system, linking them to a template and then adding new hosts will apply those checks with their same settings across the list of new targets. Hosts and check bundles can then be removed, deactivated and unlinked allowing flexibility to work on one off servers or remove them from your monitoring infrastructure.

Fields

_cid string
The primary key
"/template/1701"
A string containing a template cid
_last_modified number
The point in time when this object was last updated.
1384217101
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
check_bundles array
The master (source) check bundles that this template will create and modify the other check bundles it manages modeled after.
[{"bundle_id":"/check_bundle/12310","name":"HTTP Monitoring"},{"bundle_id":"/check_bundle/12314","name":"Resmon Monitoring"}]
Removing existing values from this list requires passing a bundle_removal_action parameter (see the 'Updating a template' documentation). Required
object (zero or more times)
An object
bundle_id string
The check bundle that will be cloned for each host
A string containing a check_bundle cid
name string
The name assigned to the cloned check bundles
A string containing freeform text. Any instance of the string '{target}' in this string will automatically be replaced by the hostname or IP that this particular check bundle was cloned for
hosts array
The hostnames and/or IP addresses for which the template will create and manage check bundles
["www1.example.com","www2.example.com","www3.example.com","www4.example.com","www5.example.com","www6.example.com"]
An array. Removing existing values from this list requires passing a host_removal_action parameter (see the 'Updating a template' documentation). Required
string (one or more times)
A single hostname / IP address for which the template will create and manage check bundles
A string containing freeform text
master_host string
The master host of a template is the host which all checks are copied from.
"www1.example.com"
A string containing freeform text. Required
name string
The name of the template
"Webserver Template"
A string containing freeform text. Required
notes string
A free form text field for storing notes about this template.
"This is the templated monitoring applied to all our webservers"
A string containing freeform text
status string
The status of the template
"active"
A string. Must be either 'active' / 'synced' (indicating normal template status), unsynced (indicating the template was recently modified it is waiting to be synced), inprogress (indicating the system is in the middle of syncing the template to all the hosts), or inactive (indicating the template is no longer in use)
sync_rules boolean
Should this template sync rulesets from the check bundle also?
Either true or false. Optional, default false
tags array
["webservers"]
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 Templates

Fetching details for a template is as simple as peforming a GET on the template cid:

GET /template/1701
{"master_host":"www1.example.com","notes":"This is the templated monitoring applied to all our webservers","tags":["webservers"],"hosts":["www1.example.com","www2.example.com","www3.example.com","www4.example.com","www5.example.com","www6.example.com"],"_last_modified_by":"/user/923","_cid":"/template/1701","_last_modified":1384217101,"name":"Webserver Template","check_bundles":[{"name":"HTTP Monitoring","bundle_id":"/check_bundle/12310"},{"name":"Resmon Monitoring","bundle_id":"/check_bundle/12314"}],"status":"active"}

From this we can see some important things:

Creating Templates

Creating a new template is as simple as making a HTTP POST request to /template and passing JSON representing the new template:

POST /template
{"hosts":["imap1.example.com","imap2.example.com"],"check_bundles":[{"bundle_id":"/check_bundle/89318","name":"IMAP monitoring"}],"name":"IMAP Template","master_host":"imap.example.com"}

As is usual, the POST request returns the full JSON in the response (incuding the new templates's cid, and any default and read only values)

The check bundles that you use to create the template must already exist and must refer to the passed master_host.

Updating a Template

Graphs can be updated simply by using the PUT HTTP method with new field values:

PUT /template/1701
{"hosts":["www1.example.com","www2.example.com","www3.example.com","www4.example.com","www5.example.com","www6.example.com","www7.example.com"]}

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

When you remove a host or check_bundle from a template (i.e. whenever you fail to pass a host or check_bundle in the data structure that previously existed in that data structure) you must specify what should happen to the current checks in Circonus. You can control the behaviour by appending the host_removal_action and/or bundle_removal_action parameters to the query string.

The values you may pass are as follows:

unbind
Marks the check(s) as unbound from the template, you can then modify them as if they were a "normal" check
deactivate
Sets the check(s) as inactive, they will still show up on the interface and you can view historic data for them
remove
Deletes the check(s) from the system, they will no longer show in the UI and historic data will be gone

For example, if you wanted to decommission www2 and stop monitoring it, but keep the data for it around (i.e. to show just how broken it was and why you decommissioned it):

PUT /template/1701?host_removal_action=deactivate
{"hosts":["www1.example.com","www3.example.com","www4.example.com","www5.example.com","www6.example.com","www7.example.com"]}

Similarly, if you later decide you need to collect different statistics for different webservers - and you now want to manually adjust what metrics the RESMON checks you have created on a per host basis - you can stop the RESMON checks from being managed by the template by removing the master check bundle from the check_bundles field. By telling Circonus to just unbind the check bundles (and leave them in place but not managed by the template) you can keep historic data and you can manually tweak them later:

PUT /template/1701?bundle_removal_action=unbind
{"check_bundles":[{"bundle_id":"/check_bundle/12310","name":"HTTP Monitoring"}]}

Listing and Searching Templates

Templates can be listed simply by performing a HTTP GET request on /template.

GET /template
[{"check_bundles":[{"name":"HTTP Monitoring","bundle_id":"/check_bundle/12310"}],"status":"active","name":"Webserver Template","_last_modified":1384217101,"_cid":"/template/1701","hosts":["www1.example.com","www3.example.com","www4.example.com","www5.example.com","www6.example.com","www7.example.com"],"tags":["webservers"],"_last_modified_by":"/user/923","notes":"This is the templated monitoring applied to all our webservers","master_host":"www1.example.com"},{"master_host":"imap.example.com","_last_modified_by":"/user/923","tags":[],"hosts":["imap1.example.com","imap2.example.com"],"notes":null,"_last_modified":1384219748,"_cid":"/template/1792","check_bundles":[{"name":"IMAP monitoring","bundle_id":"/check_bundle/89318"}],"status":"active","name":"IMAP Template"}]

You can search in the usual way, for example to find a template with a particular name:

GET /template?search=IMAP%20Template
[{"_last_modified":1384219748,"_cid":"/template/1792","status":"active","check_bundles":[{"bundle_id":"/check_bundle/89318","name":"IMAP monitoring"}],"name":"IMAP Template","master_host":"imap.example.com","tags":[],"hosts":["imap1.example.com","imap2.example.com"],"_last_modified_by":"/user/923","notes":null}]

Or all templates with a particular tag:

GET /template?search=(tags%3Awebservers)
[{"tags":["webservers"],"_last_modified_by":"/user/923","hosts":["www1.example.com","www3.example.com","www4.example.com","www5.example.com","www6.example.com","www7.example.com"],"notes":"This is the templated monitoring applied to all our webservers","master_host":"www1.example.com","check_bundles":[{"bundle_id":"/check_bundle/12310","name":"HTTP Monitoring"}],"status":"active","name":"Webserver Template","_last_modified":1384217101,"_cid":"/template/1701"}]

Removing Templates

Templates can be removed by using the DELETE HTTP method on the cid:

DELETE /template/1701

The template will no longer be listed when listing or searching for templates, though you will be able to see the inactive template if you explictly request its cid:

GET /template/1701
{"_cid":"/template/1701","_last_modified":1384219012,"name":"Webserver Template","status":"inactive","check_bundles":[],"master_host":"www1.example.com","notes":"This is the templated monitoring applied to all our webservers","tags":["webservers"],"_last_modified_by":"/user/923","hosts":[null]}