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.

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.