class

Crometheus::Histogram

Inherits Crometheus::Metric / Reference / Object

Histogram is a Metric type that tracks how many observations fit into a series of ranges, or buckets. Each bucket is defined by its upper bound. Whenever #observe is called, the value of each bucket with a bound equal to or greater than the observed value is incremented. A running sum of all observed values is also tracked.

require "crometheus/histogram"

buckets = Crometheus::Histogram.linear_buckets(60, 30, 10)
# => [60.0, 90.0, 120.0, ... , 300.0, 330.0, Infinity]

hold_times = Crometheus::Histogram.new(
  :hold_times, "Time spent on hold", buckets: buckets)
hold_times.observe 35.4
hold_times.observe 214.1
hold_times.observe 179.0
hold_times.observe 118.0
hold_times.observe 384.4

under_2_min = hold_times.buckets[120.0] / hold_times.count # => 0.4

Constructors

new(name : Symbol, docstring : String, register_with : Crometheus::Registry | Nil = Crometheus.default_registry, buckets : Array(Float | Int) = @@default_buckets)

In addition to the standard arguments for Metric.new, takes an array that defines the range of each bucket. The .linear_buckets and .geometric_buckets convenience methods may be used to generate an appropriate array. A bucket for Infinity will be added if it is not already part of the array. If left unspecified, buckets will default to [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, +Inf].

Source

Class methods

geometric_buckets(start, factor, bucket_count) : Array(Float64)

Returns an array of geometrically-increasing bucket upper bounds suitable for passing into the constructor of Histogram. bucket_count excludes the Infinity bucket.

require "crometheus/histogram"
include Crometheus

hist = Histogram.new(:powers, "powers of two",
  buckets: Histogram.geometric_buckets(1, 2, 4))

hist.buckets # => {1.0 => 0.0, 2.0 => 0.0, 4.0 => 0.0,
#     8.0 => 0.0, Infinity => 0.0}

Source

linear_buckets(start, step, bucket_count) : Array(Float64)

Returns an array of linearly-increasing bucket upper bounds suitable for passing into the constructor of Histogram. bucket_count excludes the Infinity bucket.

require "crometheus/histogram"
include Crometheus

hist = Histogram.new(:evens, "even teens",
  buckets: Histogram.linear_buckets(12, 2, 4))

hist.buckets # => {12.0 => 0.0, 14.0 => 0.0, 16.0 => 0.0,
#     18.0 => 0.0, Infinity => 0.0}

Source

type

Returns Type::Histogram. See Metric.type.

Source

valid_label?(label : Symbol)

In addition to the standard Metric.valid_label? behavior, returns false if a label is :le. Histograms reserve this label for bucket upper bounds.

Source