utils::statistics::Percentile< M, Counter, ExtraBuckets, ExtraBucketSize > Class Template Reference

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

Detailed Description

template<std::size_t M, typename Counter = std::uint32_t, std::size_t ExtraBuckets = 0, std::size_t ExtraBucketSize = 500>
class utils::statistics::Percentile< M, Counter, ExtraBuckets, ExtraBucketSize >

Class allows easy calculation of percentiles.

Stores M + ExtraBuckets buckets of type Counter.

On Account(x) the bucket to increment is chosen depending on x value. If x belongs to:

• [0, M), then bucket from M buckets;
• [M, M + ExtraBuckets * ExtraBucketSize), then bucket from ExtraBuckets;
• all the bigger values, then last bucket from ExtraBuckets.

On GetPercentile(percent) class sums up the required amount of buckets, knowing the total count of Account(x) invocations.

Template Parameters

M	buckets count for value step of 1
Counter	type of all the buckets
ExtraBuckets	buckets for value step of ExtraBucketSize
ExtraBucketSize	ExtraBuckets store values with this precision

See also

GetPercentile

Account

Example: Precisely count for first 500 milliseconds of execution using std::uint32_t counters and leave 100 buckets for all the other values with precision of 9 milliseconds:

using Percentile = utils::statistics::Percentile<500, std::uint32_t, 100, 9>;
using Timings = utils::statistics::RecentPeriod<Percentile, Percentile>;
 
void Account(Percentile& perc, std::chrono::milliseconds ms) {
  perc.Account(ms.count());
}
 
void ExtendStatistics(utils::statistics::Writer& writer, Timings& timings) {
  writer["timings"]["1min"] = timings;
}

Type is safe to read/write concurrently from different threads/coroutines.

Percentile metrics are non-summable, e.g. given RPS counts and timing percentiles for multiple hosts or handlers, we cannot accurately compute the total timing percentiles.

See also

utils::statistics::Histogram for the summable equivalent

Definition at line 66 of file percentile.hpp.

Public Member Functions
	Percentile (const Percentile< M, Counter, ExtraBuckets, ExtraBucketSize > &other) noexcept
Percentile &	operator= (const Percentile &rhs) noexcept
void	Account (std::size_t value) noexcept
	Account for another value.
std::size_t	GetPercentile (double percent) const
	Get X percentile - min value P so that total number of elements in buckets is no less than X percent.
template<class Duration = std::chrono::seconds>
void	Add (const Percentile< M, Counter, ExtraBuckets, ExtraBucketSize > &other, Duration this_epoch_duration=Duration(), Duration before_this_epoch_duration=Duration())
void	Reset () noexcept
	Zero out all the buckets and total number of elements.
Counter	Count () const noexcept
	Total number of elements.

Constructor & Destructor Documentation

Percentile() [1/2]

template<std::size_t M, typename Counter = std::uint32_t, std::size_t ExtraBuckets = 0, std::size_t ExtraBucketSize = 500>

utils::statistics::Percentile< M, Counter, ExtraBuckets, ExtraBucketSize >::Percentile ( )

inlinenoexcept

Definition at line 68 of file percentile.hpp.

Percentile() [2/2]

template<std::size_t M, typename Counter = std::uint32_t, std::size_t ExtraBuckets = 0, std::size_t ExtraBucketSize = 500>

utils::statistics::Percentile< M, Counter, ExtraBuckets, ExtraBucketSize >::Percentile ( const Percentile< M, Counter, ExtraBuckets, ExtraBucketSize > & other )

inlinenoexcept

Definition at line 74 of file percentile.hpp.

Member Function Documentation

Account()

template<std::size_t M, typename Counter = std::uint32_t, std::size_t ExtraBuckets = 0, std::size_t ExtraBucketSize = 500>

void utils::statistics::Percentile< M, Counter, ExtraBuckets, ExtraBucketSize >::Account ( std::size_t value )

inlinenoexcept

Account for another value.

1 is added to the bucket corresponding to value

Definition at line 102 of file percentile.hpp.

Add()

template<std::size_t M, typename Counter = std::uint32_t, std::size_t ExtraBuckets = 0, std::size_t ExtraBucketSize = 500>

template<class Duration = std::chrono::seconds>

void utils::statistics::Percentile< M, Counter, ExtraBuckets, ExtraBucketSize >::Add ( const Percentile< M, Counter, ExtraBuckets, ExtraBucketSize > & other, Duration this_epoch_duration = Duration(), Duration before_this_epoch_duration = Duration() )

inline

Definition at line 151 of file percentile.hpp.

Count()

template<std::size_t M, typename Counter = std::uint32_t, std::size_t ExtraBuckets = 0, std::size_t ExtraBucketSize = 500>

Counter utils::statistics::Percentile< M, Counter, ExtraBuckets, ExtraBucketSize >::Count ( ) const

inlinenoexcept

Total number of elements.

Definition at line 177 of file percentile.hpp.

GetPercentile()

template<std::size_t M, typename Counter = std::uint32_t, std::size_t ExtraBuckets = 0, std::size_t ExtraBucketSize = 500>

std::size_t utils::statistics::Percentile< M, Counter, ExtraBuckets, ExtraBucketSize >::GetPercentile ( double percent ) const

inline

Get X percentile - min value P so that total number of elements in buckets is no less than X percent.

Parameters

percent

- value in [0..100] - requested percentile. If outside of 100, then returns last bucket that has any element in it.

Definition at line 125 of file percentile.hpp.

operator=()

template<std::size_t M, typename Counter = std::uint32_t, std::size_t ExtraBuckets = 0, std::size_t ExtraBucketSize = 500>

Percentile & utils::statistics::Percentile< M, Counter, ExtraBuckets, ExtraBucketSize >::operator= ( const Percentile< M, Counter, ExtraBuckets, ExtraBucketSize > & rhs )

inlinenoexcept

Definition at line 79 of file percentile.hpp.

Reset()

template<std::size_t M, typename Counter = std::uint32_t, std::size_t ExtraBuckets = 0, std::size_t ExtraBucketSize = 500>

void utils::statistics::Percentile< M, Counter, ExtraBuckets, ExtraBucketSize >::Reset ( )

inlinenoexcept

Zero out all the buckets and total number of elements.

Definition at line 170 of file percentile.hpp.

---

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

• userver/utils/statistics/percentile.hpp