class Crometheus::Histogram

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:

crometheus/histogram.cr

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from class Crometheus::Metric

docstring : String docstring, name : Symbol name, samples(&block : Sample -> Nil) : Nil samples

Constructor methods inherited from class Crometheus::Metric

new(name : Symbol, docstring : String, register_with : Crometheus::Registry? = Crometheus.default_registry) new

Class methods inherited from class Crometheus::Metric

type type, valid_label?(label : Symbol) : Bool valid_label?

Constructor Detail

def self.new(name : Symbol, docstring : String, register_with : Crometheus::Registry? = 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].


[View source]

Class Method Detail

def self.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}

[View source]
def self.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}

[View source]
def self.type #

Returns Type::Histogram. See Metric.type.


[View source]
def self.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.


[View source]

Instance Method Detail

def buckets : Hash(Float64, Float64) #

A mapping of upper bounds to bucket values.


[View source]
def count : Float64 #

Returns the value of the Infinity bucket. This is equal to the total number of observations performed by this histogram.


[View source]
def measure_runtime(&block) #

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


[View source]
def observe(value) #

Increments the value of all buckets whose range includes value. Also increases #sum by value.


[View source]
def reset #

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


[View source]
def samples(&block : Sample -> Nil) #

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


[View source]
def sum : Float64 #

A running sum of all observed values.


[View source]