API Documentation | Metric Cluster

A metric cluster is a cluster of metrics defined by a set of queries.


_cid string
The primary key
A string containing a metric_cluster cid
_matching_metrics array
The matching metrics. Only available as a extra field (see example below for explanation).
An array
string (zero or more times)
A metric in the cluster
A string containing a fully qualified metric name in the format <digits>_<string>.
_matching_uuid_metrics object
The matching metrics with check_uuid prefixes. Only available as a extra field (see example below for explanation).
An object
description string
Description of the metric cluster
"All web requests"
A string containing freeform text. Optional.
name string
The name of the metric cluster
"All Web Rates"
A string containing freeform text. Required
queries array
The queries that determine which metrics are in this cluster
[{"type":"count","query":"module:nginx total_requests"},{"query":"module:apache request_count","type":"count"}]
An array
object (zero or more times)
An individual query
An object
query string
The query string that will be applied against the metric
A string containing freeform text
type string
The type of metric that the query will matched against
A string containing either 'average', 'count', 'counter', 'counter_stddev', 'derive', 'derive_stddev', 'histogram', 'stddev' or 'text'
tags array
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.


Fetching Metric Clusters

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

GET /metric_cluster/131
{"description":"All web requests","tags":["datacenter:primary"],"_cid":"/metrics_cluster/131","queries":[{"type":"count","query":"module:nginx total_requests"},{"type":"count","query":"module:apache request_count"}],"name":"All Web Rates"}

You'll notice a few important things:

  • The metric cluster has both a name and a description, as well as the usual tags
  • queries field contains all the queries that define what is contained in the cluster.

Fetching Matching Metrics

It's possible to use the API to get a list of what the current matching metrics are by passing the extra=_matching_metrics query parameter:

GET /metric_cluster/131?extra=_matching_metrics
{"description":"All web requests","tags":["datacenter:primary"],"_matching_metrics":["42123_total_requests","42124_total_requests","14121_total_requests","86412_request_count","86415_request_count"],"queries":[{"query":"module:nginx total_requests","type":"count"},{"type":"count","query":"module:apache request_count"}],"name":"All Web Rates","_cid":"/metrics_cluster/131"}

You can also get the same matching metric list categorized by check_uuid by passing: extra=_matching_uuid_metrics query parameter:

GET /metric_cluster/131?extra=_matching_uuid_metrics
{"_matching_uuid_metrics":[{"6692c87b-4855-c2be-abf7-acbb828a7dae":["total_requests"]},{"b8cc0c49-1ba1-ea53-ba17-9c52823798c0":["total_requests"]},{"861d8820-ed30-efa3-f60d-f03431a708ca":["total_requests"]},{"677cb723-0e22-41ea-e8c2-ab3fe88f47ca":["request_count"]},{"98bf3c58-c7c2-6615-ff95-859eee452c2a":["request_count"]}],"tags":["datacenter:primary"],"description":"All web requests","name":"All Web Rates","queries":[{"type":"count","query":"module:nginx total_requests"},{"query":"module:apache request_count","type":"count"}],"_cid":"/metrics_cluster/131"}

Creating a Metric Cluster

Creating a new metrics cluster is as simple as making a HTTP POST request to /metric_cluster and passing JSON representing the new metric cluster:

POST /metric_cluster
{"tags":["datacenter:primary"],"description":"All web requests","queries":[{"type":"count","query":"module:nginx total_requests"},{"type":"count","query":"module:apache request_count"}],"name":"All Web Rates"}

Updating a Metric Cluster

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

PUT /metric_cluster/131
{"name":"A Rose That Smells as Sweet"}

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

Altering the queries for the metric cluster can be updated the same way, by simply altering the queries list to contain the new queries you want and passing it, along with the other values, during a HTTP PUT to the original cid.

PUT /metric_cluster/131
{"queries":[{"type":"count","query":"module:nginx total_requests"}]}

The API intelligently examines the new field values and automatically adds and removes queries as needed.

Listing and Searching Metric Clusters

Metric clusters can be listed simply by performing a HTTP GET request on /metric_cluster. You can search in the usual way, for example to list all clusters with the word "All" in the name:

GET /metric_cluster?search=*All*
[{"_cid":"/metrics_cluster/131","name":"A Rose That Smells as Sweet","queries":[{"type":"count","query":"module:nginx total_requests"}],"description":"All web requests","tags":["datacenter:primary"]}]

Or all the clusters with the datacenter:primary tag:

GET /metric_cluster?search=(tags%3A=datacenter:primary)
[{"tags":["datacenter:primary"],"description":"All web requests","_cid":"/metrics_cluster/131","name":"A Rose That Smells as Sweet","queries":[{"type":"count","query":"module:nginx total_requests"}]}]

Removing Metric Clusters

Metric clusters can be simply removed by using the DELETE HTTP method on the cid:

DELETE /metric_clusters/154