Circonus is a telemetry collecting platform. It is not focused on log data, nor on documents. Each piece of data should be concise and representative of the metric to which it is attached. Collected data is broken down into four types: numeric, text, histogram, and beacons.


Text data in Circonus is a brief, terse measurement that is designed to express a system's current state. The values are limited to 512 bytes of data. The typical uses for the text data type are SSH fingerprints, SSL certificate subjects, software version numbers, and response codes (such as HTTP response codes).

For those not familiar with HTTP response codes, they are actually restricted by the numeric range in the HTTP specification, but interpreting them as numbers makes no analytical sense. Each response code (and range) has unique meaning and thus using statistical aggregates (such as mean or stddev) would be nonsensical.


Numeric data is as simple as it sounds: a number. Examples include the number of visitors to a website, the number of database transactions executed, the amount of traffic push from a network interface, the revenues, the number of bytes used on a disk, or the temperature outside.

Numeric types in Circonus have no units (e.g. visitors, transaction, octets, $USD, bytes, Celsius, etc.). Unit information is not included as there are no limits on the type of units in which numbers may be submitted. In the event that the units are not self evident from the raw metric name, it is advisable to name metrics in the system such that the base units are obvious. Common convention is to include a suffix, such as "_dollars", "_visitors", or "_ms" for milliseconds.

When Circonus stores numeric data, it aggregates collected data into one minute windows. Within this window, we track:

  • count - the total number of sample,
  • average/gauge - the average of the samples
  • stddev - the standard deviation across the samples
  • derive - the first order derivative over the samples
  • derive_stddev - the standard deviation over the 'derive' samples
  • counter - the first order derivative ignoring decreases in sample value
  • counter_stddev - the standard deviation over the 'counter' samples

  • The "counter" type is used to determine the rate of change of telemetry data you know is monotonically increasing, but due to technical details can "reset" to a lower value (often zero). If you know that a rate can never legitimately be negative (such as bandwidth or arrivals/second or transactions/second), then the "counter" aggregate is the interesting aggregate of the bunch.


    Histograms are designed for understand high velocity data. Histogram data will store all samples reduced to two significant digits in base ten. (E.g. 0.1 through 9.9 at increments of 0.1, 10 through 99 at increments of 1, 100 through 990 at increments of 10, etc.) It handles values from (+/-)10^127 to (+/-)10^-128 and zero.

    The histogram type stores the counts of samples in one minute time chunks (or "buckets"). Statistical information can be calculated from the histogram with error introduced from the bucketing.


    Beacon data is the one data type within Circonus that is not stored permanently. Beacons are deprecated feature, and are no longer used, except for legacy purposes.