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	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...

ObservationPtr	getObservation (const std::string &name) const
	Returns an observation. 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...

void	setMaxSampleAge (const std::string &name, const StatsDuration &duration)
	Determines maximum age of samples. More...

void	setMaxSampleCount (const std::string &name, uint32_t max_samples)
	Determines how many samples of a given statistic should be kept. 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...

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 StatsMgr &	instance ()
	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...

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 61 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.

Parameters

stat	observation

Todo:: : Implement contexts.

Definition at line 68 of file stats_mgr.cc.

Referenced by 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 375 of file lib/stats/stats_mgr.h.

References getObservation(), and setValue().

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

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 225 of file lib/stats/stats_mgr.h.

◆ getObservation()

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

Returns an observation.

Used in testing only. Production code should use get() method.

Parameters

name	name of the statistic

Returns: Pointer to the Observation object

Todo:: : Implement contexts.

Definition at line 62 of file stats_mgr.cc.

Referenced by addValueInternal(), get(), reset(), and setValueInternal().

◆ instance()

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

static

Statistics Manager accessor method.

Definition at line 21 of file stats_mgr.cc.

Referenced by isc::ha::HAImpl::buffer4Receive(), isc::ha::HAImpl::buffer6Receive(), isc::dhcp::Dhcpv4Srv::processPacket(), isc::dhcp::Dhcpv4Srv::processStatsReceived(), isc::dhcp::Dhcpv4Srv::processStatsSent(), statisticGetAllHandler(), statisticGetHandler(), statisticRemoveAllHandler(), statisticRemoveHandler(), statisticResetAllHandler(), and statisticResetHandler().

◆ 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 350 of file lib/stats/stats_mgr.h.

References addObservation(), and getObservation().

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

◆ addValueInternal()

◆ generateName()

◆ getObservation()

◆ instance()

◆ setValueInternal()