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.

2015-12-02_Circonus_Histogram_range%20copy.png