userver: utils::statistics::Histogram Class Reference
Loading...
Searching...
No Matches
utils::statistics::Histogram Class Referencefinal

#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::Histogram histogram{std::vector<double>{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:

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)
 
 Histogram (HistogramView other)
 Copies an existing histogram.
 
 Histogram (Histogram &&) noexcept
 
 Histogram (const Histogram &)
 
Histogramoperator= (Histogram &&) noexcept
 
Histogramoperator= (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.


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