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
Indicates whether data has been collected for this metric within the active time window. The default time window is the last 8 hours. The active window can be specified by setting the active_start and active_end query parameters.
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'
_status string
Indicates whether this metric has been set to actively collect data or is available to collect data but is not currently enabled.
A string containing either 'active' or 'available'
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
{"tags":["os:linux"],"_metric_type":"numeric","_cid":"/metric/4373_tt_firstbyte","_active":true,"_histogram":"false","_check":"/check/4373","_metric_name":"tt_firstbyte","_check_uuid":"40679dd2-83f9-46ae-8c0e-2019f6f88f02","_check_active":true,"units":"milliseconds"}

From this we can see some important things:

  • A metric cid consists of the check number, underscore, and the metric name.
  • We're monitoring the "tt_firstbyte" (time till first byte) metric of the check "/check/4373".
  • The metric is actively being collected and its Check is also active.
  • The units the metric collects are being reported as 'milliseconds'.

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)
[{"_metric_type":"numeric","tags":["os:linux"],"_cid":"/metric/4373_tt_firstbyte","_active":true,"_histogram":"false","_check_uuid":"40679dd2-83f9-46ae-8c0e-2019f6f88f02","_metric_name":"tt_firstbyte","_check":"/check/4373","_check_active":"true","units":"milliseconds"},{"_active":true,"_cid":"/metric/4373_duration","_histogram":"false","tags":[],"_metric_type":"numeric","units":"milliseconds","_check_active":"true","_check":"/check/4373","_metric_name":"duration","_check_uuid":"40679dd2-83f9-46ae-8c0e-2019f6f88f02"},"\u2026"]

Metric Search Query Parameters

In addition to the query parameters described in the Circonus API Search documentation, the metric service also accepts the following query parameters.

  • start or activity_start_secs: The start of the range of time in which to search for metric activity in IRONdb. The value must be an integer representing the number of seconds since the Unix epoch. The default value used, if omitted, is one month before the current time.
  • end or activity_end_secs: The end of the range of time in which to search for metric activity in IRONdb. The value must be an integer representing the number of seconds since the Unix epoch. The default value used, if omitted, is the current time.
  • active_start: The start of the range of time in which, if metric activity is found in IRONdb, the metric will be considered active. This is reflected by a value of true for the _active field. The value must be an integer representing the number of seconds since the Unix epoch. The default value used, if omitted, eight hours before the current time.
  • active_end: The end of the range of time in which, if metric activity is found in IRONdb, the metric will be considered active. This is reflected by a value of true for the _active field. The value must be an integer representing the number of seconds since the Unix epoch. The default value used, if omitted, is the current time.

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.