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.

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 >

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");

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::dhcp::Dhcpv4Srv::declineLease(), isc::dhcp::Dhcpv6Srv::declineLease(), 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::Dhcpv4Srv::processRelease(), isc::dhcp::Dhcpv6Srv::releaseIA_NA(), isc::dhcp::Dhcpv6Srv::releaseIA_PD(), isc::d2::D2TsigKey::resetStats(), isc::dhcp::Dhcpv4Srv::serverDecline(), 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.

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

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ addObservation()

◆ addObservationInternal()

◆ addValueInternal()

◆ generateName()

◆ getObservation()

◆ getObservationInternal()

◆ instance()

◆ setValueInternal()