Estimate event rates over a trailing measurement period. More...

#include <event_rate_estimator.hpp>

Public Types
typedef std::vector< counter_type >	buckets

Type traits.
typedef duration_t	duration_type

typedef counter_t	counter_type

Public Member Functions
	event_rate_estimator (duration_type measurement_period, duration_type sampling_period=duration_type(1))
	Build an accumulator to estimate event rates. More...

template<typename functor >
void	sample (duration_type ts, functor update)
	Record a sample. More...

Private Member Functions
void	init (duration_type ts)
	Just initialize the circular buffer. More...

void	rotate ()
	Rotate the circular buffer. More...

std::size_t	bucket_count (duration_type measurement_period, duration_type sampling_period)
	Estimate the necessary number of buckets. More...

Private Attributes
buckets	buckets_
	The time period is bucketized in intervals of 1 sampling period. More...

duration_type	sampling_period_
	The sampling period. More...

std::uint64_t	running_total_
	Current number of events across all buckets. More...

duration_type::rep	last_bucket_
	Current number for the sampling period. More...

std::size_t	end_pos_
	We treat the buckets as a circular buffer, this is the pointer to the end of the buffer. More...

Detailed Description

template<typename duration_t = std::chrono::microseconds, typename counter_t = int>
class jb::event_rate_estimator< duration_t, counter_t >

Estimate event rates over a trailing measurement period.

Assume you are interested in statistics about events per millisecond. This class estimates the number of events per trailing millisecond, using an arbitrary sampling period. For example, you could set the sampling period to 1 microsecond, this class would then estimate the event rate over the previous millisecond for every microsecond. Or you could set the sampling period to 1 millisecond, which would then estimate the event rate on each millisecond. Admittedly, for most practical purposes measuring event rates over an exact millisecond boundary or over a trailing millisecond has limited interest, but it was fun to write this class.

Given a measurement_period: the time over which we want to measure event rates, and sampling_period: how often we want to measure the event rates, the class keeps a circular buffer of N counters, representing the trailing sampling periods. N is chosen such that \( N > {{measurement\_period} \over {sampling\_period}} \).

As new events arrive the counter for the current sampling period is incremented, once an event in a new sampling period is observed the class emits updates (via a functor) to update the estimated event rate.

Template Parameters

duration_t Defines class used to measure time, this class must be compatible with std::chrono::duration_type. The class assumes that event timestamps are measured as durations with respect to some well-defined (by convention) epoch. For example, some data feeds use timestamps as nanoseconds since midnight, while others use timestamps as microseconds since the Unix Epoch.

counter_t The type of the counters, most of the time a simple integer would work well, but if you need to create a large number of instances of this class, and the values are expected to be very small, you might consider using a 16-bit or even and 8-bit counter. Likewise, if you expect very large values for the counters, such as when measuring event rate per minute, you should consider using a 64-bit counter.

Definition at line 58 of file event_rate_estimator.hpp.

Member Typedef Documentation

◆ buckets

template<typename duration_t = std::chrono::microseconds, typename counter_t = int>

typedef std::vector<counter_type> jb::event_rate_estimator< duration_t, counter_t >::buckets

Definition at line 146 of file event_rate_estimator.hpp.

◆ counter_type

template<typename duration_t = std::chrono::microseconds, typename counter_t = int>

typedef counter_t jb::event_rate_estimator< duration_t, counter_t >::counter_type

Definition at line 65 of file event_rate_estimator.hpp.

◆ duration_type

template<typename duration_t = std::chrono::microseconds, typename counter_t = int>

typedef duration_t jb::event_rate_estimator< duration_t, counter_t >::duration_type

Definition at line 64 of file event_rate_estimator.hpp.

Constructor & Destructor Documentation

◆ event_rate_estimator()

template<typename duration_t = std::chrono::microseconds, typename counter_t = int>

jb::event_rate_estimator< duration_t, counter_t >::event_rate_estimator	(	duration_type	measurement_period,
		duration_type	sampling_period = `duration_type(1)`
	)

inline

Build an accumulator to estimate event rates.

Parameters

measurement_period	over what time period we want to measure message rates
sampling_period	how often do we want to measure message rates. Must be smaller than measurement_period.

Exceptions

std::invalid_argument if the measurement period is not a multiple of the sampling period.

Definition at line 78 of file event_rate_estimator.hpp.

Member Function Documentation

◆ bucket_count()

template<typename duration_t = std::chrono::microseconds, typename counter_t = int>

std::size_t jb::event_rate_estimator< duration_t, counter_t >::bucket_count	(	duration_type	measurement_period,
		duration_type	sampling_period
	)

inlineprivate

Estimate the necessary number of buckets.

Definition at line 169 of file event_rate_estimator.hpp.

◆ init()

template<typename duration_t = std::chrono::microseconds, typename counter_t = int>

void jb::event_rate_estimator< duration_t, counter_t >::init ( duration_type ts )

inlineprivate

Just initialize the circular buffer.

Definition at line 150 of file event_rate_estimator.hpp.

Referenced by jb::event_rate_estimator< duration_type, rate_counter_type >::sample().

◆ rotate()

template<typename duration_t = std::chrono::microseconds, typename counter_t = int>

void jb::event_rate_estimator< duration_t, counter_t >::rotate ( )

inlineprivate

Rotate the circular buffer.

Definition at line 158 of file event_rate_estimator.hpp.

Referenced by jb::event_rate_estimator< duration_type, rate_counter_type >::sample().

◆ sample()

template<typename duration_t = std::chrono::microseconds, typename counter_t = int>

template<typename functor >

void jb::event_rate_estimator< duration_t, counter_t >::sample	(	duration_type	ts,
		functor	update
	)

inline

Record a sample.

This class keeps the number of events observed over the last N sampling periods. New events in the same sampling period are simply recorded, but no rate estimate is made. When a timestamp in a new sampling period is required to record a sample, the update() functor is called to register the new measurements.

Parameters

ts	the timestamp of the sample.
update	a functor to update when an event rate is estimated.

Definition at line 101 of file event_rate_estimator.hpp.

Referenced by BOOST_AUTO_TEST_CASE(), and jb::event_rate_histogram< std::chrono::nanoseconds, std::int64_t >::sample().

Member Data Documentation

◆ buckets_

template<typename duration_t = std::chrono::microseconds, typename counter_t = int>

buckets jb::event_rate_estimator< duration_t, counter_t >::buckets_

private

The time period is bucketized in intervals of 1 sampling period.

Definition at line 213 of file event_rate_estimator.hpp.

Referenced by jb::event_rate_estimator< duration_type, rate_counter_type >::init(), jb::event_rate_estimator< duration_type, rate_counter_type >::rotate(), and jb::event_rate_estimator< duration_type, rate_counter_type >::sample().

◆ end_pos_

template<typename duration_t = std::chrono::microseconds, typename counter_t = int>

std::size_t jb::event_rate_estimator< duration_t, counter_t >::end_pos_

private

We treat the buckets as a circular buffer, this is the pointer to the end of the buffer.

Definition at line 226 of file event_rate_estimator.hpp.

Referenced by jb::event_rate_estimator< duration_type, rate_counter_type >::init(), jb::event_rate_estimator< duration_type, rate_counter_type >::rotate(), and jb::event_rate_estimator< duration_type, rate_counter_type >::sample().

◆ last_bucket_

template<typename duration_t = std::chrono::microseconds, typename counter_t = int>

duration_type::rep jb::event_rate_estimator< duration_t, counter_t >::last_bucket_

private

Current number for the sampling period.

Definition at line 222 of file event_rate_estimator.hpp.

Referenced by jb::event_rate_estimator< duration_type, rate_counter_type >::init(), jb::event_rate_estimator< duration_type, rate_counter_type >::rotate(), and jb::event_rate_estimator< duration_type, rate_counter_type >::sample().

◆ running_total_

template<typename duration_t = std::chrono::microseconds, typename counter_t = int>

std::uint64_t jb::event_rate_estimator< duration_t, counter_t >::running_total_

private

Current number of events across all buckets.

Definition at line 219 of file event_rate_estimator.hpp.

Referenced by jb::event_rate_estimator< duration_type, rate_counter_type >::init(), jb::event_rate_estimator< duration_type, rate_counter_type >::rotate(), and jb::event_rate_estimator< duration_type, rate_counter_type >::sample().

◆ sampling_period_

template<typename duration_t = std::chrono::microseconds, typename counter_t = int>

duration_type jb::event_rate_estimator< duration_t, counter_t >::sampling_period_

private

The sampling period.

Definition at line 216 of file event_rate_estimator.hpp.

Referenced by jb::event_rate_estimator< duration_type, rate_counter_type >::init(), and jb::event_rate_estimator< duration_type, rate_counter_type >::sample().

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

jb/event_rate_estimator.hpp

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

template<typename duration_t = std::chrono::microseconds, typename counter_t = int> class jb::event_rate_estimator< duration_t, counter_t >

Member Typedef Documentation

◆ buckets

◆ counter_type

◆ duration_type

Constructor & Destructor Documentation

◆ event_rate_estimator()

Member Function Documentation

◆ bucket_count()

◆ init()

◆ rotate()

◆ sample()

Member Data Documentation

◆ buckets_

◆ end_pos_

◆ last_bucket_

◆ running_total_

◆ sampling_period_

template<typename duration_t = std::chrono::microseconds, typename counter_t = int>
class jb::event_rate_estimator< duration_t, counter_t >