prometheus::Histogram Class Reference

A histogram metric to represent aggregatable distributions of events. More...

#include <histogram.h>

Public Types
using	BucketBoundaries = std::vector< double >

Public Member Functions
	Histogram (const BucketBoundaries &buckets)
	Create a histogram with manually chosen buckets.
	Histogram (BucketBoundaries &&buckets)
	Create a histogram with manually chosen buckets.
void	Observe (double value)
	Observe the given amount.
void	ObserveMultiple (const std::vector< double > &bucket_increments, double sum_of_values)
	Observe multiple data points.
void	Reset ()
	Reset all data points collected so far.
ClientMetric	Collect () const
	Get the current value of the histogram.

Static Public Attributes
static const MetricType	metric_type {MetricType::Histogram}

Detailed Description

A histogram metric to represent aggregatable distributions of events.

This class represents the metric type histogram: https://prometheus.io/docs/concepts/metric_types/#histogram

A histogram tracks the number of observations and the sum of the observed values, allowing to calculate the average of the observed values.

At its core a histogram has a counter per bucket. The sum of observations also behaves like a counter as long as there are no negative observations.

See https://prometheus.io/docs/practices/histograms/ for detailed explanations of histogram usage and differences to summaries.

The class is thread-safe. No concurrent call to any API of this type causes a data race.

Constructor & Destructor Documentation

Histogram() [1/2]

prometheus::Histogram::Histogram ( const BucketBoundaries &  buckets )

explicit

Create a histogram with manually chosen buckets.

The BucketBoundaries are a list of monotonically increasing values representing the bucket boundaries. Each consecutive pair of values is interpreted as a half-open interval [b_n, b_n+1) which defines one bucket.

There is no limitation on how the buckets are divided, i.e, equal size, exponential etc..

The bucket boundaries cannot be changed once the histogram is created.

Histogram() [2/2]

prometheus::Histogram::Histogram ( BucketBoundaries &&  buckets )

explicit

Create a histogram with manually chosen buckets.

The BucketBoundaries are a list of monotonically increasing values representing the bucket boundaries. Each consecutive pair of values is interpreted as a half-open interval [b_n, b_n+1) which defines one bucket.

There is no limitation on how the buckets are divided, i.e, equal size, exponential etc..

The bucket boundaries cannot be changed once the histogram is created.

Member Function Documentation

Collect()

ClientMetric prometheus::Histogram::Collect

(

)

const

Get the current value of the histogram.

Collect is called by the Registry when collecting metrics.

Observe()

void prometheus::Histogram::Observe

(

double

value

)

Observe the given amount.

The given amount selects the 'observed' bucket. The observed bucket is chosen for which the given amount falls into the half-open interval [b_n, b_n+1). The counter of the observed bucket is incremented. Also the total sum of all observations is incremented.

ObserveMultiple()

void prometheus::Histogram::ObserveMultiple	(	const std::vector< double > &	bucket_increments,
		double	sum_of_values
	)

Observe multiple data points.

Increments counters given a count for each bucket. (i.e. the caller of this function must have already sorted the values into buckets). Also increments the total sum of all observations by the given value.

Reset()

void prometheus::Histogram::Reset

(

)

Reset all data points collected so far.

All buckets and sum are reset to its oringal value. This is especially useful if histogram is tracked elsewhere but report in prometheus system.