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.