A Circonus histogram is represented as a list of buckets. From a mathematical perspective, in Circonus, these buckets consist of the following data:

A bucket is a pair of a bucket_boundary and a bucket_count.

- The bucket_count is an unsigned 64-bit integer
- The bucket_bound is a float value that can be represented as:

bucket_bound = x * 10^e- where x is one of the following float values:

x = -9.9, -9.8, -9.7 .. -1.1, -1.0, 0, 1.0, 1.1, .. ,9.9 - and e is an 8-bit integer:

e = -128 .. 127 - The representation of a bucket_bound is unique, except for the case bucket_bound = 0.

- where x is one of the following float values:

Here are some examples:

- 1 = 1.0 * 10^0
- 15 = 1.5 * 10^1
- The smallest/largest positive bucket boundary are:

p_min = 1.0 * 10^-128 = 10^-128

p_max = 9.9 * 10^127 - The smallest/largest negative bucket boundaries are:

n_min = - 9.9 * 10^127

n_max = - 1.0 * 10^-128 = 10^-128 - There are precisely 90 buckets for each "order of magnitude" +/-10^e:

x=1.0,1.1,...,1.9; 2.0,2.1,....2.9; ...;9.0,9.1,...,9.9

A histogram bucket, represented by (bound, count), means that a number of "count" values have been recorded in the following interval.

Write bound = x * 10^e as above, then

- If x > 0 then, the bucket interval is:

[ x * 10^e, (x + 0.1) * 10^e )

with inclusive left, exclusive right. - If x = 0 then the bucket interval is the single value 0:

{ 0 } - If x < then the bucket interval is:

( (x - 0.1) * 10^e, x * 10^e ]

with exclusive left, inclusive right.

For example:

- bound = 0, yields interval = { 0 }
- bound = 1, yields interval = [1, 1.1)
- bound = 9, yields interval = [9, 9.1)
- bound = 9.9, yields interval = [9.9, 9.9 + 0.1 = 10)
- bound = 10, yields interval = [10, 11)
- bound = -1, yields interval = (-1.1, -1]

However, there are some edge cases:

- Values above or equal to 1e128 are illegal
- Values below or equal to -1e128 are illegal
- Values between (n_max, p_min) (exclusive) are treated as 0.

We do not enforce an artificial bound on the number of buckets per histogram. However, there is a theoretical maximum of 46.081 buckets per histogram. Indeed, buckets are indexed by pairs (x, e):

- There are 180 = 2*90 nonzero options for x
- There are 256 options for e

This gives 46080 - non-zero buckets, plus the 0 bucket. In practice, we have never seen the theoretical maximum being reached. Measured quantities are not spanning ten orders of magnitude; e.g. 12032 and 0.000000000000000214 are not two values which a single metric is likely to assume.

Usually histograms do not exceed a number of 200 buckets. Expect performance penalties when using more than ~300 buckets in a histogram metric.