Collect statistics and generate log messages. More...

#include <senf/Utils/Statistics.hh>

Inheritance diagram for senf::Statistics:

Public Member Functions
	Statistics ()

void	operator() (unsigned n, unsigned cnt, float min, float avg, float max, float dev)
	Enter new data. More...

void	operator() (unsigned cnt, float min, float avg, float max, float dev=0.0f)
	Same as operator() with n==1. More...

void	operator() (unsigned cnt, float value, float dev=0.0f)
	Same as operator() with min == avg == max. More...

void	operator() (StatisticsData const &data)
	Same as operator(), but imports statistics data from a StatisticsData object. More...

template<class Value >
void	operator() (unsigned n, StatisticAccumulator< Value > &sa)
	Same as operator() gathers values from StatisticAccumulator. More...

StatisticsBase::OutputProxy< Statistics >	output (unsigned n=1u)

Public Member Functions inherited from senf::StatisticsBase
StatisticsData	data () const
	Get the Statistics data as senf::StatisticsData. More...

void	consoleList (unsigned level, std::ostream &os) const

unsigned	cnt () const
	Last cnt value entered. More...

float	min () const
	Last min value entered. More...

float	avg () const
	Last avg value entered. More...

float	max () const
	Last max value entered. More...

float	dev () const
	Last dev value entered. More...

virtual unsigned	rank () const
	Return collectors rank value. More...

Collector &	operator[] (unsigned rank)
	Get child collector. More...

Collector const &	operator[] (unsigned rank) const
	Get child collector. More...

CollectorRange	collectors ()
	List all child collectors. More...

const_CollectorRange	collectors () const
	List all child collectors. More...

Collector &	collect (unsigned rank)
	Register a new collector. More...

Statistics const &	base () const

Statistics &	base ()
	Get base statistics object. More...

std::string	path () const
	Get the path to this collector. More...

OutputProxy< StatisticsBase >	output (unsigned n=1u)
	Register output. More...

Public Attributes
console::ScopedDirectory	dir

Additional Inherited Members
Public Types inherited from senf::StatisticsBase
typedef boost::iterator_range< ValueIterator >	CollectorRange

typedef boost::iterator_range< const_ValueIterator >	const_CollectorRange

Protected Member Functions inherited from senf::StatisticsBase
	StatisticsBase ()

virtual	~StatisticsBase ()

void	enter (unsigned n, unsigned cnt, float min, float avg, float max, float dev)

Detailed Description

Collect statistics and generate log messages.

The Statistics class collects information about a single value. The assumption is, that Statistics::operator() is called periodically to supply new data.

Each data entry is comprised of a minimum, average and maximum value. These values should describe the value of whatever parameter is analyzed by a Statistics instance over the last period. The length of the period is defined by the interval, at which data is entered.

The Statistics class combines successive data values into ever larger groups. These groups form a tree where each node combines a fixed number of data values of it's parent node. An example:

Let us assume, that Statistics::operator() is called every 100ms. We can than build a chain of collectors:

The basic statistics module provides information with a resolution of 1/10th of a second
A collector collecting 10 values provides information with 1 second resolution
The next collector collects 60 values and provides a resolution of 1 minute
Again the next collector collects 60 values and provides a resolution of 1 hour
... and so on

This way, we create a hierarchy of values. Each collector manages a minimum, average and maximum value always created over it's the last complete interval.

It is possible to have more than one collector based on the same basic interval. In above scenario, we might want to add another collector which for example collects information with a 100 second scale. This is possible and changes the list of collectors into a tree.

Now to turn all this into code:

senf::ppi::module::RateAnalyzer rateAnalyzer;
senf::Statistics packetStats;
rateAnalyzer.signals.packetsPerSecond.connect(boost::ref(packetStats));
packetStats                      // called 10 times / second
    .collect(10u)                // seconds
    .collect(60u)                // minutes
    .collect(60u);               // hours
packetStats[10u].collect(100u);  // 100 seconds
rateAnalyzer.startStatistics(senf::ClockService::milliseconds(100u));

    This code will collect the statistics as described in the Example above. However, no output
    will be generated.

    For every collector, any number of outputs may be defined. Each output consists of the
    number of values to calculate a sliding average over and an identifying label.

    Lets say, we want to produce the following outputs:
    \li A sliding average of 5 values based on the raw 1/10th second data.
    \li Three different outputs from the seconds statistics: current value without average,
        sliding average over 10 seconds and sliding average over 60 seconds.
    \li Output the minutes and hourly value without averaging.

    To achieve this, we can augment above code in the following way:

packetStats
        .output( 5u).connect(senf::StatisicsLogger("pps 100ms 5"))
    .collect(10u)
        .output(   ).noconnect()
        .output(10u).connect(senf::StatisicsLogger("pps 1s 10"))
        .output(60u).connect(senf::StatisicsLogger("pps 1s 60"))
    .collect(60u)
        .output(   ).connect(senf::StatisicsLogger("pps 1min 1"))
    .collect(60u)
        .output(   ).connect(senf::StatisicsLogger("pps 1h 1"));
packetStats.output(5u).connect(
    senf::StatisticsLogger<senf::log::Debug, senf::log::VERBOSE>("pps"));
senf::log::FileTarget statslog ("stats.log");
statslog.showArea(false);
statslog.showLevel(false);
statslog.tag("");
statslog.timeFormat("");
statslog.route<senf::StatisticsStream>();

    We use a StatisticsLogger to send the %log messages to the senf::StatisticsStream %log
    stream. The stream, area an level to send the statistics %log messages to may be configured
    using template arguments to StatisticsLogger.

    It is also possible to skip sending the output to any target or send one output to several
    targets.

    Here we have opted to use a label which explicitly describes the name of the variable, the
    basic interval and the size of the sliding average window. However, the label is completely
    arbitrary.

    All output is generated using the Senf Logger on the senf::StatisticsStream %log stream. In
    the example above, we have configured a special logfile \c stats.log which contains the
    statistics values each prefixed with a timestamp in nanoseconds (but no further information
    like %log level or tag):

0000000000.000000000 pps 100ms 5 43.3 43.3 43.3
0000000000.010311928 pps 100ms 5 42.5 42.5 42.5
...
0000000001.002413391 pps 100ms 5 62.0 62.0 62.0
0000000001.003920018 pps 1s 1 42.1 53.4 62.0
...

(the nanosecond values will of course be somewhat different ...)

See also: senf::StatisticsBase::OutputProxy for the output proxy (connect) interface

Definition at line 435 of file Statistics.hh.

Constructor & Destructor Documentation

◆ Statistics()

senf::Statistics::Statistics ( )

Definition at line 184 of file Statistics.cc.

Member Function Documentation

◆ operator()() [1/5]

void senf::Statistics::operator()	(	unsigned	n,
		unsigned	cnt,
		float	min,
		float	avg,
		float	max,
		float	dev
	)

Enter new data.

This member must be called whenever new data is available.

If min and max values are not available, this member should be called with min, avg and max set to the same value. If no error estimate is available, call with dev = 0.

In the most common case, this member is to be called periodically and n will be 1 on all calls. The interval, at which this member is called then defines the statistics time scale.

Calling with n > 1 will submit the value n times. This makes it possible to aggregate multiple time slices into a single call. This does not change the basic time scale but can change the number of submits per unit time. If the basic time slice is small, this allows to submit values almost arbitrarily non-periodic.

Parameters

[in]	n	number of time-slices
[in]	min	minimal data value since last call
[in]	avg	average data value since last call
[in]	max	maximal data values since last call
[in]	dev	standard deviation of avg value

◆ operator()() [2/5]

void senf::Statistics::operator()	(	unsigned	cnt,
		float	min,
		float	avg,
		float	max,
		float	dev = `0.0f`
	)

Same as operator() with n==1.

Provided so a Statistics instance can be directly used as a signal target.

◆ operator()() [3/5]

void senf::Statistics::operator()	(	unsigned	cnt,
		float	value,
		float	dev = `0.0f`
	)

Same as operator() with min == avg == max.

Provided so a Statistics instance can be directly used as a signal target.

◆ operator()() [4/5]

void senf::Statistics::operator() ( StatisticsData const & data )

Same as operator(), but imports statistics data from a StatisticsData object.

Provided so a Statistics instance can be directly used as a signal target.

◆ operator()() [5/5]

template<class Value >

void senf::Statistics::operator()	(	unsigned	n,
		StatisticAccumulator< Value > &	sa
	)

Same as operator() gathers values from StatisticAccumulator.

Provided so a Statistics instance can be directly used as a signal target. Caution: Clears values in StatisticAccumulator afterwards

Parameters

[in]	n	number of time-slices
[in]	sa	StatisticAccumulator

◆ output()

StatisticsBase::OutputProxy<Statistics> senf::Statistics::output ( unsigned n = 1u )

Member Data Documentation

◆ dir

console::ScopedDirectory senf::Statistics::dir

Definition at line 440 of file Statistics.hh.

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

SENF Extensible Network Framework

Public Member Functions

Public Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Statistics()

Member Function Documentation

◆ operator()() [1/5]

◆ operator()() [2/5]

◆ operator()() [3/5]

◆ operator()() [4/5]

◆ operator()() [5/5]

◆ output()

Member Data Documentation

◆ dir