API Documentation | Metric

Provides API access to individual Metrics. Fields are generally read-only (configurable by creating and modifying Check Bundles); however, you can update the 'units' field to represent an arbitrary unit of measurement (e.g., bytes, seconds, milliseconds) or the 'tags' field to add and remove metric tags.

Note that a 'units' value and any 'tags' assigned to a metric are always applied to the same metric across all Checks within the same CheckBundle.

The cid for a Metric consists of the Check ID followed by an underscore followed by the metric name.

Fields

_cid string
The primary key
"/metric/4373_tt_firstbyte"
A string containing a metric cid
_active boolean
If this metric is being collected or not.
true
Either true or false
_check string
CID of the Check which collects this metric.
"/check/4373"
A string containing a check cid
_check_active boolean
If the Check containing this metric is active or not.
true
Either true or false
_check_bundle string
CID of the Check Bundle containing the check which collects this metric.
A string containing a check_bundle cid
_check_tags array
Tag(s) on the Check Bundle containing the check which collects this metric.
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.
_check_uuid string
UUID of the Check which collects this metric.
"40679dd2-83f9-46ae-8c0e-2019f6f88f02"
A string containing freeform text
_histogram string
Whether data on this metric is collected in histogram form.
"false"
A string containing either 'active', 'inactive' or 'false'
_metric_name string
The name of the metric.
"tt_firstbyte"
A string containing freeform text
_metric_type string
The type of values the metric returns
"numeric"
A string containing either 'numeric' or 'text'
link string
deprecated. See ruleset link.
A string containing freeform text
notes string
deprecated. See ruleset notes.
A string containing freeform text
tags array
Tag(s) assigned to the individual metric. Changes to a metric's tags will be applied to the same metric across all Checks in the same CheckBundle.
["os:linux"]
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). Changes to the 'units' value will be applied to the same metric across all Checks in the same CheckBundle.
"milliseconds"
A string containing freeform text

Example

Fetching a Metric

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

GET /metric/4373_tt_firstbyte
{"_created_on":"2015-05-13 16:14:20.498997-04","_metric_name":"tt_firstbyte","_cid":"/metric/4373_tt_firstbyte","_check_active":true,"_metric_type":"numeric","_last_modified_on":"2015-05-13 16:14:20.498997-04","_check":"/check/4373","units":"milliseconds","_check_uuid":"40679dd2-83f9-46ae-8c0e-2019f6f88f02","_active":true,"tags":["os:linux"],"_histogram":"false"}

From this we can see some important things:

Updating a Metric

Metrics are managed by creating and modifying Check Bundles. However, you can use the API to change a metric's metadata by issuing a PUT request to the metric cid.

NOTE: when changing metadata of an individual metric, that change will also be applied to the same metric of any other Checks within that same CheckBundle. To create unique tags/units for the same metric(s) across different Brokers, create one CheckBundle for each Broker and update the metrics accordingly.

To change a metric's units:

PUT /metric/4373_tt_firstbyte
{"units":"milliseconds"}

To "unset" or "clear" the units setting from a metric, set units to an empty string:

PUT /metric/4373_tt_firstbyte
{"units":""}

To change the tags associated with the individual metric:

PUT /metric/4373_tt_firstbyte
{"tags":["tag:one","tag:two"]}

To "unset" or "clear" the tags from a metric, set tags to an empty array:

PUT /metric/4373_tt_firstbyte
{"tags":[]}

Listing and Searching Metrics

Metrics can be listed simply by performing a GET request on /metric. Use the Circonus API Search facility to narrow down the list. For example to list only the metrics belonging to check /check/4373:

GET /metric?search=(check_id:4373)
[{"_last_modified_on":"2016-02-29 16:14:20.498997-04","_metric_type":"numeric","_check_active":"true","_check":"/check/4373","_created_on":"2016-02-29 16:14:20.498997-04","_metric_name":"tt_firstbyte","_cid":"/metric/4373_tt_firstbyte","_histogram":"false","tags":["os:linux"],"_active":true,"_check_uuid":"40679dd2-83f9-46ae-8c0e-2019f6f88f02","units":"milliseconds"},{"_last_modified_on":"2016-02-29 16:14:20.498997-04","_check_active":"true","_metric_type":"numeric","_check":"/check/4373","_created_on":"2016-02-29 16:14:20.498997-04","_metric_name":"duration","_cid":"/metric/4373_duration","_histogram":"false","tags":[],"_active":true,"units":"milliseconds","_check_uuid":"40679dd2-83f9-46ae-8c0e-2019f6f88f02"},"\u2026"]

Creating and Deleting Metrics

Metrics are created and deleted automatically by creating and deleting Checks in the Circonus system. See the CheckBundle API for more information.