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
A string containing a check_bundle cid
An array of tags. The tags in the array are automatically sorted, deduplicated and transformed into their lowercase canonical form.
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.
A string containing freeform text
A string containing freeform text
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 Metric
Fetching details for a metric is as simple as performing a GET on the metric cid:
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:
To "unset" or "clear" the units setting from a metric, set units to an empty string:
To change the tags associated with the individual metric:
To "unset" or "clear" the tags from a metric, set tags to an empty array:
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
:
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.

Circonus Keyboard Shortcuts
Jump Navigation
docs
- Jump to the user documentation.
Application Shortcuts
?
- Show this keyboard help screen.
<esc>
- Close help screens and dialogs.
/
- Focus on any available search field.
r
- Refresh content on the page without reloading the entire page; currently works on graphs, worksheets, and dashboards.
Graph Grid Shortcuts
<shift>
- On a worksheet, hold it down to invert the current legend hover
setting.
On “My Graphs” and the “Trending & Analytics Dash,” hold it down to show the legend when hovering over a graph.
Graph Shortcuts
<comma>
- Hold down to show the date shifting toolbar for modifying the start date. Can be combined with <period>.
<period>
- Hold down to show the date shifting toolbar for modifying the end date. Can be combined with <comma>.
<ctrl>+<alt>+<left>
- Nudge the date range for the current graph(s) backward.
<ctrl>+<alt>+<right>
- Nudge the date range for the current graph(s) forward.
h
- Toggle the display of histogram sparklines (shown upon hovering over a graph when viewing or when on a dashboard).
s
- Hold down to unlock graph hovering datapoint selection, allowing mouse hovering to select nearby datapoints.
Mousewheel & Touchpad Shortcuts
<shift>
- Hold down while scrolling to zoom graphs' Y axes.
<alt>
- Hold down while scrolling to zoom graphs' X axis.
<ctrl>+<alt>
- Hold down while scrolling to shift graphs' X axis.
<comma>
- Hold down while scrolling to shift graphs' X axis start dates. Can be combined with <period>.
<period>
- Hold down while scrolling to shift graphs' X axis end dates. Can be combined with <comma>.