senf::Statistics Class Reference
[Statistics]

Collect statistics and generate log messages. More...

#include <senf/Utils/Statistics.hh>

Inheritance diagram for senf::Statistics:
Inheritance graph
[legend]

List of all members.

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:

  • A sliding average of 5 values based on the raw 1/10th second data.
  • Three different outputs from the seconds staistics: current value without average, sliding average over 10 seconds and sliding average over 60 seconds.
  • 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 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 422 of file Statistics.hh.


Public Member Functions
  Statistics ()
void  operator() (unsigned n, float min, float avg, float max, float dev)
  Enter new data.
void  operator() (float min, float avg, float max, float dev=0.0f)
  Same as operator() with n==1.
void  operator() (float value, float dev=0.0f)
  Same as operator() with min == avg == max.
void  operator() (StatisticsData const &data)
  Same as operator(), but imports statistics data from a StatisticsData object.
template<class Value >
void  operator() (unsigned n, StatisticAccumulator< Value > &sa)
  Same as operator() gathers values from StatisticAccumulator.
StatisticsBase::OutputProxy
< Statistics > 		 output (unsigned n=1u)
  Register output.
void  consoleList (std::ostream &os)
void  consoleCollect (std::vector< unsigned > &ranks)
boost::shared_ptr
< senf::console::DirectoryNode > 		 consoleOutput (std::vector< unsigned > &ranks, unsigned window)

Public Attributes
console::ScopedDirectory
< Statistics > 		 dir

Constructor & Destructor Documentation

senf::Statistics::
Statistics ()

Definition at line 167 of file Statistics.cc.

Member Function Documentation

void senf::Statistics::
consoleCollect ( std::vector< unsigned > &  ranks )

Definition at line 236 of file Statistics.cc.

void senf::Statistics::
consoleList ( std::ostream &  os )

Definition at line 230 of file Statistics.cc.

boost::shared_ptr< senf::console::DirectoryNode > senf::Statistics::
consoleOutput ( std::vector< unsigned > &  ranks,
unsigned  window )

Definition at line 254 of file Statistics.cc.

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

Definition at line 92 of file Statistics.cti.

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.

Definition at line 175 of file Statistics.cci.

void senf::Statistics::
operator() ( 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.

Definition at line 180 of file Statistics.cci.

void senf::Statistics::
operator() ( 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.

Definition at line 170 of file Statistics.cci.

void senf::Statistics::
operator() ( unsigned  n,
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

Definition at line 164 of file Statistics.cci.

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

Register output.

This call will request the collector to output statistics build by averaging the last n values. This output is generated for every new value in the collector. The output signal can be connected to an arbitrary target using the returned proxy. Example:

stats.output(4u).connect(
    senf::StatisticsLogger());
Parameters:
[in]  n  size of sliding average window

Reimplemented from senf::StatisticsBase.

Definition at line 187 of file Statistics.cci.

Member Data Documentation

console::ScopedDirectory<Statistics> senf::Statistics::
dir

Definition at line 427 of file Statistics.hh.

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