class Crometheus::Histogram

• Crometheus::Histogram
• Crometheus::Metric
• Reference
• Object

Overview

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

Defined in:

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.

Class Method Summary

• .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.

• .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.

• .type

  Returns Type::Histogram.

• .valid_label?(label : Symbol)

  In addition to the standard Metric.valid_label? behavior, returns false if a label is :le.

Instance Method Summary

• #buckets : Hash(Float64, Float64)

  A mapping of upper bounds to bucket values.

• #count : Float64

  Returns the value of the Infinity bucket.

• #measure_runtime(&)

  Yields to the block, then passes the block's runtime to #observe.

• #observe(value)

  Increments the value of all buckets whose range includes value.

• #reset

  Resets all bucket values, as well as #sum, to 0.0.

• #samples(&block : Sample -> Nil) : Nil

  Yields one Sample for each bucket, in addition to one for #count (equal to the infinity bucket) and one for #sum.

• #sum : Float64

  A running sum of all observed values.

Constructor Detail

Class Method Detail

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}

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}

Instance Method Detail