utils::statistics::Histogram Class Reference

#include <userver/utils/statistics/histogram.hpp>

Detailed Description

A histogram with a dynamically-allocated array of buckets.

Histogram metrics

• A histogram metric is a list of counters ("buckets") with specified bounds
• The implicit lowest bound is always 0
• Bucket bounds must follow the ascending order
• Values on the bucket borders fall into the lower bucket
• Besides normal buckets, there is also a special "infinity" bucket, which contains values that are greater than the greatest bucket bound
• Each individual counter has the semantics of utils::statistics::Rate
• For best portability, there should be no more than 50 buckets

Histograms vs utils::statistics::Percentile

See also

utils::statistics::Percentile is a related metric type

The trade-offs of histograms with Percentile are:

1. Percentile metrics are fundamentally non-summable across multiple hosts. Histogram, on the other hand, are summable
2. A Histogram takes up more storage space on the statistics server, as there are typically 20-50 buckets in a Histogram, but only a few required percentiles in a Percentile
3. Percentile metrics have almost infinite precision, limited only by the number of allocated atomic counters. The precision of Histogram metrics is limited by the initially set bounds

Usage of Histogram

Usage example:

    utils::statistics::Storage storage;
 
    utils::statistics::Histogram histogram{{1.5, 5, 42, 60}};
 
    auto statistics_holder =
        storage.RegisterWriter("test", [&](utils::statistics::Writer& writer) { writer = histogram; });
 
    histogram.Account(10);
    histogram.Account(1.2);
    histogram.Account(1.8);
    histogram.Account(100);
    histogram.Account(30, 4);  // Account 4 times
 
    const utils::statistics::Snapshot snapshot{storage};
    EXPECT_EQ(fmt::to_string(snapshot.SingleMetric("test")), "[1.5]=1,[5]=1,[42]=5,[60]=0,[inf]=1");

Contents of a Histogram are read using utils::statistics::HistogramView. This can be useful for writing custom metric serialization formats or for testing.

Histogram metrics can be summed using utils::statistics::HistogramAggregator.

Histogram can be used in utils::statistics::MetricTag:

utils::statistics::MetricTag<utils::statistics::Histogram> kRuntimeHistogramMetric{
    "histogram_metric_sample_runtime",
    Bounds()};
 
void AccountHistogram(utils::statistics::MetricsStorage& metrics_storage) {
    metrics_storage.GetMetric(kRuntimeHistogramMetric).Account(10);
}

Definition at line 63 of file histogram.hpp.

Public Member Functions
	Histogram (utils::span< const double > upper_bounds)
	Sets upper bounds for each non-"infinite" bucket. The lowest bound is always 0.
	Histogram (HistogramView other)
	Copies an existing histogram.
	Histogram (Histogram &&) noexcept
	Histogram (const Histogram &)
Histogram &	operator= (Histogram &&) noexcept
Histogram &	operator= (const Histogram &)
void	Account (double value, std::uint64_t count=1) noexcept
	Atomically increment the bucket corresponding to the given value.
HistogramView	GetView () const &noexcept
	Allows reading the histogram.

Constructor & Destructor Documentation

Histogram()

utils::statistics::Histogram::Histogram ( utils::span< const double > upper_bounds )

explicit

Sets upper bounds for each non-"infinite" bucket. The lowest bound is always 0.

Parameters

upper_bounds

is copied inside and is not required to be kept alive after the constructor completes.

---

The documentation for this class was generated from the following file:

• userver/utils/statistics/histogram.hpp