Kea  2.1.7-git
isc::stats::StatsMgr Class Reference

Statistics Manager class. More...

#include <stats_mgr.h>

+ Inheritance diagram for isc::stats::StatsMgr:

Public Member Functions

void addObservation (const ObservationPtr &stat)
 Adds a new observation. More...
 
void addObservationInternal (const ObservationPtr &stat)
 Adds a new observation in a thread safe context. More...
 
void addValue (const std::string &name, const int64_t value)
 Records incremental integer observation. More...
 
void addValue (const std::string &name, const double value)
 Records incremental floating point observation. More...
 
void addValue (const std::string &name, const StatsDuration &value)
 Records incremental duration observation. More...
 
void addValue (const std::string &name, const std::string &value)
 Records incremental string observation. More...
 
template<typename DataType >
void addValueInternal (const std::string &name, DataType value)
 Adds specified value to a given statistic (internal version). More...
 
size_t count () const
 Returns number of available statistics. More...
 
bool del (const std::string &name)
 Removes specified statistic. More...
 
isc::data::ConstElementPtr get (const std::string &name) const
 Returns a single statistic as a JSON structure. More...
 
isc::data::ConstElementPtr getAll () const
 Returns all statistics as a JSON structure. More...
 
const StatsDurationgetMaxSampleAgeDefault () const
 Get default duration limit. More...
 
uint32_t getMaxSampleCountDefault () const
 Get default count limit. More...
 
ObservationPtr getObservation (const std::string &name) const
 Returns an observation. More...
 
ObservationPtr getObservationInternal (const std::string &name) const
 Returns an observation in a thread safe context. More...
 
size_t getSize (const std::string &name) const
 Returns size of specified statistic. More...
 
void removeAll ()
 Removes all collected statistics. More...
 
bool reset (const std::string &name)
 Resets specified statistic. More...
 
void resetAll ()
 Resets all collected statistics back to zero. More...
 
bool setMaxSampleAge (const std::string &name, const StatsDuration &duration)
 Determines maximum age of samples. More...
 
void setMaxSampleAgeAll (const StatsDuration &duration)
 Set duration limit for all collected statistics. More...
 
void setMaxSampleAgeDefault (const StatsDuration &duration)
 Set default duration limit. More...
 
bool setMaxSampleCount (const std::string &name, uint32_t max_samples)
 Determines how many samples of a given statistic should be kept. More...
 
void setMaxSampleCountAll (uint32_t max_samples)
 Set count limit for all collected statistics. More...
 
void setMaxSampleCountDefault (uint32_t max_samples)
 Set default count limit. More...
 
void setValue (const std::string &name, const int64_t value)
 Records absolute integer observation. More...
 
void setValue (const std::string &name, const double value)
 Records absolute floating point observation. More...
 
void setValue (const std::string &name, const StatsDuration &value)
 Records absolute duration observation. More...
 
void setValue (const std::string &name, const std::string &value)
 Records absolute string observation. More...
 
template<typename DataType >
void setValueInternal (const std::string &name, DataType value)
 Sets a given statistic to specified value (internal version). More...
 
isc::data::ConstElementPtr statisticSetMaxSampleAgeAllHandler (const isc::data::ConstElementPtr &params)
 Handles statistic-sample-age-set-all command. More...
 
isc::data::ConstElementPtr statisticSetMaxSampleCountAllHandler (const isc::data::ConstElementPtr &params)
 Handles statistic-sample-count-set-all command. More...
 

Static Public Member Functions

template<typename Type >
static std::string generateName (const std::string &context, Type index, const std::string &stat_name)
 Generates statistic name in a given context. More...
 
static StatsMgrinstance ()
 Statistics Manager accessor method. More...
 
static isc::data::ConstElementPtr statisticGetAllHandler (const std::string &name, const isc::data::ConstElementPtr &params)
 Handles statistic-get-all command. More...
 
static isc::data::ConstElementPtr statisticGetHandler (const std::string &name, const isc::data::ConstElementPtr &params)
 Handles statistic-get command. More...
 
static isc::data::ConstElementPtr statisticRemoveAllHandler (const std::string &name, const isc::data::ConstElementPtr &params)
 Handles statistic-remove-all command. More...
 
static isc::data::ConstElementPtr statisticRemoveHandler (const std::string &name, const isc::data::ConstElementPtr &params)
 Handles statistic-remove command. More...
 
static isc::data::ConstElementPtr statisticResetAllHandler (const std::string &name, const isc::data::ConstElementPtr &params)
 Handles statistic-reset-all command. More...
 
static isc::data::ConstElementPtr statisticResetHandler (const std::string &name, const isc::data::ConstElementPtr &params)
 Handles statistic-reset command. More...
 
static isc::data::ConstElementPtr statisticSetMaxSampleAgeHandler (const std::string &name, const isc::data::ConstElementPtr &params)
 Handles statistic-sample-age-set command. More...
 
static isc::data::ConstElementPtr statisticSetMaxSampleCountHandler (const std::string &name, const isc::data::ConstElementPtr &params)
 Handles statistic-sample-count-set command. More...
 

Detailed Description

Statistics Manager class.

StatsMgr is a singleton class that represents a subsystem that manages collection, storage and reporting of various types of statistics. It is also the intended API for both core code and hooks.

As of May 2015, Tomek ran performance benchmarks (see unit-tests in stats_mgr_unittest.cc with performance in their names) and it seems the code is able to register ~2.5-3 million observations per second, even with 1000 different statistics recorded. That seems sufficient for now, so there is no immediate need to develop any multi-threading solutions for now. However, should this decision be revised in the future, the best place for it would to be modify addObservation method here. It's the common code point that all new observations must pass through. One possible way to enable multi-threading would be to run a separate thread handling collection. The main thread would call addValue and setValue methods that would end up calling addObservation. That method would pass the data to separate thread to be collected and would immediately return. Further processing would be mostly as it is today, except happening in a separate thread. One unsolved issue in this approach is how to extract data, but that will remain unsolvable until we get the control socket implementation.

Statistics Manager does not use logging by design. The reasons are:

  • performance impact (logging every observation would degrade performance significantly. While it's possible to log on sufficiently high debug level, such a log would be not that useful)
  • dependency (statistics are intended to be a lightweight library, adding dependency on libkea-log, which has its own dependencies, including external log4cplus, is against 'lightweight' design)
  • if logging of specific statistics is warranted, it is recommended to add log entries in the code that calls StatsMgr.
  • enabling logging in StatsMgr does not offer fine tuning. It would be either all or nothing. Adding logging entries only when necessary in the code that uses StatsMgr gives better granularity.

If this decision is revisited in the future, the most universal places for adding logging have been marked in addValueInternal and setValueInternal.

Definition at line 63 of file lib/stats/stats_mgr.h.

Member Function Documentation

◆ addObservation()

void isc::stats::StatsMgr::addObservation ( const ObservationPtr stat)

Adds a new observation.

That's an utility method used by public setValue() and addValue() methods. Calls addObservationInternal() method in a thread safe context.

Parameters
statobservation

Definition at line 134 of file lib/stats/stats_mgr.cc.

Referenced by addValueInternal().

◆ addObservationInternal()

void isc::stats::StatsMgr::addObservationInternal ( const ObservationPtr stat)

Adds a new observation in a thread safe context.

That's an utility method used by public setValue() and addValue() methods. Should be called in a thread safe context.

Parameters
statobservation
Todo:
: Implement contexts.

Definition at line 144 of file lib/stats/stats_mgr.cc.

Referenced by addValueInternal(), and setValueInternal().

◆ addValueInternal()

template<typename DataType >
void isc::stats::StatsMgr::addValueInternal ( const std::string &  name,
DataType  value 
)
inline

Adds specified value to a given statistic (internal version).

This template method adds specified value to a given statistic (identified by name to a value). This internal method is used by public setValue methods.

Template Parameters
DataTypeone of int64_t, double, StatsDuration or string
Parameters
namename of the statistic
valuespecified statistic will be set to this value
Exceptions
InvalidStatTypeis statistic exists and has a different type.

Definition at line 515 of file lib/stats/stats_mgr.h.

References addObservation(), addObservationInternal(), getObservationInternal(), and setValueInternal().

+ Here is the call graph for this function:

◆ generateName()

template<typename Type >
static std::string isc::stats::StatsMgr::generateName ( const std::string &  context,
Type  index,
const std::string &  stat_name 
)
inlinestatic

Generates statistic name in a given context.

Example:

generateName("subnet", 123, "received-packets");

will return subnet[123].received-packets. Any printable type can be used as index.

Template Parameters
Typeany type that can be used to index contexts
Parameters
contextname of the context (e.g. 'subnet')
indexvalue used for indexing contexts (e.g. subnet_id)
stat_namename of the statistic
Returns
returns full statistic name in form context[index].stat_name

Definition at line 282 of file lib/stats/stats_mgr.h.

References statisticGetAllHandler(), statisticGetHandler(), statisticRemoveAllHandler(), statisticRemoveHandler(), statisticResetAllHandler(), statisticResetHandler(), statisticSetMaxSampleAgeAllHandler(), statisticSetMaxSampleAgeHandler(), statisticSetMaxSampleCountAllHandler(), and statisticSetMaxSampleCountHandler().

Referenced by isc::d2::DNSClientImpl::incrStats(), isc::d2::D2TsigKey::resetStats(), and isc::d2::D2TsigKey::~D2TsigKey().

+ Here is the call graph for this function:

◆ getObservation()

ObservationPtr isc::stats::StatsMgr::getObservation ( const std::string &  name) const

Returns an observation.

Used in testing only. Production code should use get() method when the value is dereferenced. Calls getObservationInternal() method in a thread safe context.

Parameters
namename of the statistic
Returns
Pointer to the Observation object

Definition at line 117 of file lib/stats/stats_mgr.cc.

Referenced by isc::dhcp::CfgSubnets6::updateStatistics(), and isc::dhcp::CfgSubnets4::updateStatistics().

◆ getObservationInternal()

ObservationPtr isc::stats::StatsMgr::getObservationInternal ( const std::string &  name) const

Returns an observation in a thread safe context.

Used in testing only. Production code should use get() method when the value is dereferenced. Should be called in a thread safe context.

Parameters
namename of the statistic
Returns
Pointer to the Observation object
Todo:
: Implement contexts.

Definition at line 127 of file lib/stats/stats_mgr.cc.

Referenced by addValueInternal(), and setValueInternal().

◆ instance()

◆ setValueInternal()

template<typename DataType >
void isc::stats::StatsMgr::setValueInternal ( const std::string &  name,
DataType  value 
)
inline

Sets a given statistic to specified value (internal version).

This template method sets statistic identified by name to a value specified by value. This internal method is used by public setValue methods.

Template Parameters
DataTypeone of int64_t, double, StatsDuration or string
Parameters
namename of the statistic
valuespecified statistic will be set to this value
Exceptions
InvalidStatTypeis statistic exists and has a different type.

Definition at line 491 of file lib/stats/stats_mgr.h.

References addObservationInternal(), and getObservationInternal().

Referenced by addValueInternal().

+ Here is the call graph for this function:

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