| Kea 3.0.2-git

isc::stats::StatsMgr Class Reference

Statistics Manager class. More...

`#include <stats_mgr.h>`

Inheritance diagram for isc::stats::StatsMgr:
[legend]

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

## 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.
static StatsMgr & | instance ()
| Statistics Manager accessor method.
static isc::data::ConstElementPtr | statisticGetAllHandler (const std::string &name, const isc::data::ConstElementPtr &params)
| Handles statistic-get-all command.
static isc::data::ConstElementPtr | statisticGetHandler (const std::string &name, const isc::data::ConstElementPtr &params)
| Handles statistic-get command.
static isc::data::ConstElementPtr | statisticRemoveAllHandler (const std::string &name, const isc::data::ConstElementPtr &params)
| Handles statistic-remove-all command.
static isc::data::ConstElementPtr | statisticRemoveHandler (const std::string &name, const isc::data::ConstElementPtr &params)
| Handles statistic-remove command.
static isc::data::ConstElementPtr | statisticResetAllHandler (const std::string &name, const isc::data::ConstElementPtr &params)
| Handles statistic-reset-all command.
static isc::data::ConstElementPtr | statisticResetHandler (const std::string &name, const isc::data::ConstElementPtr &params)
| Handles statistic-reset command.
static isc::data::ConstElementPtr | statisticSetMaxSampleAgeHandler (const std::string &name, const isc::data::ConstElementPtr &params)
| Handles statistic-sample-age-set command.
static isc::data::ConstElementPtr | statisticSetMaxSampleCountHandler (const std::string &name, const isc::data::ConstElementPtr &params)
| Handles statistic-sample-count-set command.

## 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 65 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

  stat | observation

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

References addObservationInternal().

Here is the call graph for this function:

## ◆ 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

  stat | observation

Todo
  : Implement contexts.

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

Referenced by addObservation(), 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

  DataType | one of int64_t, double, StatsDuration or string

Parameters

  name | name of the statistic
  value | specified statistic will be set to this value

Exceptions

  InvalidStatType | is statistic exists and has a different type.

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

References getObservationInternal(), and setValueInternal().

Referenced by addValue(), addValue(), addValue(), addValue(), and addValue().

Here is the call graph for this function:

## ◆ generateName()

template<typename Type>

std::string isc::stats::StatsMgr::generateName | ( | const std::string & | context,
|  | Type | index,
|  | const std::string & | stat_name )
| inline static

Generates statistic name in a given context.

Example:

generateName("subnet", 123, "received-packets");
isc::stats::StatsMgr::generateName
static std::string generateName(const std::string &context, Type index, const std::string &stat_name)
Generates statistic name in a given context.
Definition lib/stats/stats_mgr.h:298

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

Template Parameters

  Type | any type that can be used to index contexts

Parameters

  context | name of the context (e.g. 'subnet')
  index | value used for indexing contexts (e.g. subnet_id)
  stat_name | name of the statistic

Returns
  returns full statistic name in form context[index].stat_name

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

Referenced by isc::dhcp::Dhcpv6Srv::assignIA_NA(), isc::dhcp::Dhcpv6Srv::assignIA_PD(), isc::dhcp::Dhcpv4Srv::assignLease(), isc::gss_tsig::GssTsigImpl::createKey(), isc::dhcp::Dhcpv4Srv::declineLease(), isc::dhcp::Dhcpv6Srv::declineLease(), isc::dhcp::deleteAssignedLease(), isc::dhcp::Dhcpv6Srv::extendIA_NA(), isc::dhcp::Dhcpv6Srv::extendIA_PD(), isc::stat_cmds::LeaseStatCmdsImpl::getBigSubnetStat(), isc::stat_cmds::LeaseStatCmdsImpl::getSubnetStat(), isc::d2::DNSClientImpl::incrStats(), isc::lease_cmds::LeaseCmdsImpl::lease4WipeHandler(), isc::lease_cmds::LeaseCmdsImpl::lease6WipeHandler(), isc::dhcp::Dhcpv6Srv::processAddrRegInform(), isc::dhcp::Dhcpv4Srv::processRelease(), isc::dhcp::Dhcpv6Srv::releaseIA_NA(), isc::dhcp::Dhcpv6Srv::releaseIA_PD(), isc::dhcp::CfgSubnets4::removeStatistics(), isc::dhcp::CfgSubnets6::removeStatistics(), isc::d2::D2TsigKey::resetStats(), isc::gss_tsig::DnsServer::resetStats(), isc::dhcp::Dhcpv4Srv::serverDecline(), isc::dhcp::CfgSubnets4::updateStatistics(), isc::dhcp::CfgSubnets6::updateStatistics(), isc::lease_cmds::LeaseCmdsImpl::updateStatsOnAdd(), isc::lease_cmds::LeaseCmdsImpl::updateStatsOnAdd(), isc::lease_cmds::LeaseCmdsImpl::updateStatsOnDelete(), isc::lease_cmds::LeaseCmdsImpl::updateStatsOnDelete(), isc::lease_cmds::LeaseCmdsImpl::updateStatsOnUpdate(), and isc::lease_cmds::LeaseCmdsImpl::updateStatsOnUpdate().

## ◆ 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

  name | name of the statistic

Returns
  Pointer to the Observation object

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

References getObservationInternal().

Referenced by isc::lease_cmds::LeaseCmdsImpl::lease4WipeHandler(), isc::lease_cmds::LeaseCmdsImpl::lease6WipeHandler(), isc::dhcp::CfgSubnets4::updateStatistics(), and isc::dhcp::CfgSubnets6::updateStatistics().

Here is the call graph for this function:

## ◆ 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

  name | name of the statistic

Returns
  Pointer to the Observation object

Todo
  : Implement contexts.

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

Referenced by addValueInternal(), getObservation(), and setValueInternal().

## ◆ instance()

StatsMgr & isc::stats::StatsMgr::instance | ( |  | ) |
| static

Statistics Manager accessor method.

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

Referenced by isc::dhcp::Dhcpv4Exchange::Dhcpv4Exchange(), isc::dhcp::Dhcpv6Srv::assignIA_NA(), isc::dhcp::Dhcpv6Srv::assignIA_PD(), isc::dhcp::Dhcpv4Srv::assignLease(), buffer4_receive(), isc::ha::HAImpl::buffer4Receive(), buffer6_receive(), isc::ha::HAImpl::buffer6Receive(), isc::gss_tsig::GssTsigImpl::configure(), isc::gss_tsig::GssTsigImpl::createKey(), isc::dhcp::Dhcpv4Srv::declineLease(), isc::dhcp::Dhcpv6Srv::declineLease(), isc::dhcp::deleteAssignedLease(), isc::dhcp::Dhcpv4Srv::earlyGHRLookup(), isc::dhcp::Dhcpv6Srv::earlyGHRLookup(), isc::dhcp::Dhcpv6Srv::extendIA_NA(), isc::dhcp::Dhcpv6Srv::extendIA_PD(), isc::stat_cmds::LeaseStatCmdsImpl::getBigSubnetStat(), isc::stat_cmds::LeaseStatCmdsImpl::getSubnetStat(), isc::d2::DNSClientImpl::incrStats(), isc::d2::D2Stats::init(), isc::dhcp::Dhcpv6Srv::initContext(), isc::lease_cmds::LeaseCmdsImpl::lease4WipeHandler(), isc::lease_cmds::LeaseCmdsImpl::lease6WipeHandler(), load(), isc::d2::D2QueueMgr::operator()(), isc::dhcp::Dhcpv6Srv::processAddrRegInform(), isc::dhcp::Dhcpv4Srv::processDhcp4Query(), isc::dhcp::Dhcpv4Srv::processLocalizedQuery4(), isc::dhcp::Dhcpv6Srv::processLocalizedQuery6(), isc::dhcp::Dhcpv4Srv::processPacket(), isc::dhcp::Dhcpv6Srv::processPacket(), isc::dhcp::Dhcpv4Srv::processRelease(), isc::dhcp::Dhcpv4Srv::processStatsReceived(), isc::dhcp::Dhcpv4Srv::processStatsSent(), isc::dhcp::Dhcpv6Srv::processStatsSent(), isc::dhcp_ddns::NameChangeUDPListener::receiveCompletionHandler(), isc::dhcp::Dhcpv6Srv::releaseIA_NA(), isc::dhcp::Dhcpv6Srv::releaseIA_PD(), isc::dhcp::CfgSubnets4::removeStatistics(), isc::dhcp::CfgSubnets6::removeStatistics(), isc::perfmon::PerfMonMgr::reportToStatsMgr(), isc::d2::D2TsigKey::resetStats(), isc::gss_tsig::DnsServer::resetStats(), isc::dhcp::Dhcpv6Srv::runOne(), isc::dhcp::Dhcpv6Srv::sanityCheck(), isc::lease_query::LeaseQueryImpl4::sendResponse(), isc::lease_query::LeaseQueryImpl6::sendResponse(), isc::dhcp::Dhcpv4Srv::serverDecline(), isc::dhcp::Dhcpv4Srv::setPacketStatisticsDefaults(), isc::dhcp::Dhcpv6Srv::setPacketStatisticsDefaults(), statisticGetAllHandler(), statisticGetHandler(), statisticRemoveAllHandler(), statisticRemoveHandler(), statisticResetAllHandler(), statisticResetHandler(), statisticSetMaxSampleAgeAllHandler(), statisticSetMaxSampleAgeHandler(), statisticSetMaxSampleCountAllHandler(), statisticSetMaxSampleCountHandler(), isc::gss_tsig::GssTsigImpl::stop(), isc::ha::HAImpl::subnet4Select(), isc::ha::HAImpl::subnet6Select(), isc::dhcp::ClientHandler::tryLock(), isc::dhcp::ClientHandler::tryLock(), unload(), isc::dhcp::CfgSubnets4::updateStatistics(), isc::dhcp::CfgSubnets6::updateStatistics(), isc::dhcp::SrvConfig::updateStatistics(), isc::lease_cmds::LeaseCmdsImpl::updateStatsOnAdd(), isc::lease_cmds::LeaseCmdsImpl::updateStatsOnAdd(), isc::lease_cmds::LeaseCmdsImpl::updateStatsOnDelete(), isc::lease_cmds::LeaseCmdsImpl::updateStatsOnDelete(), isc::lease_cmds::LeaseCmdsImpl::updateStatsOnUpdate(), and isc::lease_cmds::LeaseCmdsImpl::updateStatsOnUpdate().

## ◆ 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

  DataType | one of int64_t, double, StatsDuration or string

Parameters

  name | name of the statistic
  value | specified statistic will be set to this value

Exceptions

  InvalidStatType | is statistic exists and has a different type.

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

References addObservationInternal(), and getObservationInternal().

Referenced by addValueInternal(), setValue(), setValue(), setValue(), setValue(), and setValue().

Here is the call graph for this function:

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

- lib/stats/stats_mgr.h
- lib/stats/stats_mgr.cc