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

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:

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.