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

Represents a single observable characteristic (a 'statistic') More...

#include <observation.h>

Public Types

enum  Type { STAT_INTEGER, STAT_FLOAT, STAT_DURATION, STAT_STRING }
 Type of available statistics. More...
 

Public Member Functions

 Observation (const std::string &name, const int64_t value)
 Constructor for integer observations. More...
 
 Observation (const std::string &name, const double value)
 Constructor for floating point observations. More...
 
 Observation (const std::string &name, const StatsDuration &value)
 Constructor for duration observations. More...
 
 Observation (const std::string &name, const std::string &value)
 Constructor for string observations. More...
 
void addValue (const int64_t value)
 Records incremental integer observation. More...
 
void addValue (const double value)
 Records incremental floating point observation. More...
 
void addValue (const StatsDuration &value)
 Records incremental duration observation. More...
 
void addValue (const std::string &value)
 Records incremental string observation. More...
 
DurationSample getDuration () const
 Returns observed duration sample. More...
 
std::list< DurationSamplegetDurations () const
 Returns observed duration samples. More...
 
FloatSample getFloat () const
 Returns observed float sample. More...
 
std::list< FloatSamplegetFloats () const
 Returns observed float samples. More...
 
IntegerSample getInteger () const
 Returns observed integer sample. More...
 
std::list< IntegerSamplegetIntegers () const
 Returns observed integer samples. More...
 
isc::data::ConstElementPtr getJSON () const
 Returns as a JSON structure. More...
 
std::pair< bool, StatsDurationgetMaxSampleAge () const
 Returns both values of max_sample_age_ of statistic. More...
 
std::pair< bool, uint32_t > getMaxSampleCount () const
 Returns both values of max_sample_count_ of statistic. More...
 
std::string getName () const
 Returns observation name. More...
 
size_t getSize () const
 Returns size of observed storage. More...
 
StringSample getString () const
 Returns observed string sample. More...
 
std::list< StringSamplegetStrings () const
 Returns observed string samples. More...
 
Type getType () const
 Returns statistic type. More...
 
void reset ()
 Resets statistic. More...
 
void setMaxSampleAge (const StatsDuration &duration)
 Determines maximum age of samples. More...
 
void setMaxSampleCount (uint32_t max_samples)
 Determines how many samples of a given statistic should be kept. More...
 
void setValue (const int64_t value)
 @ More...
 
void setValue (const double value)
 Records absolute floating point observation. More...
 
void setValue (const StatsDuration &value)
 Records absolute duration observation. More...
 
void setValue (const std::string &value)
 Records absolute string observation. More...
 

Static Public Member Functions

static const StatsDurationgetMaxSampleAgeDefault ()
 Get default maximum age of samples. More...
 
static uint32_t getMaxSampleCountDefault ()
 Get default maximum count of samples. More...
 
static void setMaxSampleAgeDefault (const StatsDuration &duration)
 Determines default maximum age of samples. More...
 
static void setMaxSampleCountDefault (uint32_t max_samples)
 Determines default maximum count of samples. More...
 
static std::string typeToText (Type type)
 Converts statistic type to string. More...
 

Detailed Description

Represents a single observable characteristic (a 'statistic')

Currently it supports one of four types: integer (implemented as signed 64 bit integer), float (implemented as double), time duration (implemented with millisecond precision) and string. Absolute (setValue) and incremental (addValue) modes are supported. Statistic type is determined during its first use. Once type is set, any additional observations recorded must be of the same type. Attempting to set or extract information about other types will result in InvalidStateType exception.

Observation can be retrieved in one of getInteger, getFloat, getDuration, getString (appropriate type must be used) or getJSON, which is generic and can be used for all types.

Since Kea 1.6 multiple samples are stored for the same observation.

Definition at line 84 of file observation.h.

Member Enumeration Documentation

◆ Type

Type of available statistics.

Note that those will later be exposed using control socket. Therefore an easy to understand names were chosen (integer instead of uint64). To avoid confusion, we will support only one type of integer and only one type of floating points. Initially, these are represented by int64_t and double. If convincing use cases appear to change them to something else, we may change the underlying type.

Enumerator
STAT_INTEGER 

this statistic is unsigned 64-bit integer value

STAT_FLOAT 

this statistic is a floating point value

STAT_DURATION 

this statistic represents time duration

STAT_STRING 

this statistic represents a string

Definition at line 95 of file observation.h.

Constructor & Destructor Documentation

◆ Observation() [1/4]

isc::stats::Observation::Observation ( const std::string &  name,
const int64_t  value 
)

Constructor for integer observations.

Parameters
nameobservation name
valueinteger value observed.

Definition at line 29 of file observation.cc.

References setValue().

+ Here is the call graph for this function:

◆ Observation() [2/4]

isc::stats::Observation::Observation ( const std::string &  name,
const double  value 
)

Constructor for floating point observations.

Parameters
nameobservation name
valuefloating point value observed.

Definition at line 36 of file observation.cc.

References setValue().

+ Here is the call graph for this function:

◆ Observation() [3/4]

isc::stats::Observation::Observation ( const std::string &  name,
const StatsDuration value 
)

Constructor for duration observations.

Parameters
nameobservation name
valueduration observed.

Definition at line 43 of file observation.cc.

References setValue().

+ Here is the call graph for this function:

◆ Observation() [4/4]

isc::stats::Observation::Observation ( const std::string &  name,
const std::string &  value 
)

Constructor for string observations.

Parameters
nameobservation name
valuestring observed.

Definition at line 50 of file observation.cc.

References setValue().

+ Here is the call graph for this function:

Member Function Documentation

◆ addValue() [1/4]

void isc::stats::Observation::addValue ( const int64_t  value)

Records incremental integer observation.

Parameters
valueinteger value observed
Exceptions
InvalidStatTypeif statistic is not integer

Definition at line 105 of file observation.cc.

References getInteger(), and setValue().

+ Here is the call graph for this function:

◆ addValue() [2/4]

void isc::stats::Observation::addValue ( const double  value)

Records incremental floating point observation.

Parameters
valuefloating point value observed
Exceptions
InvalidStatTypeif statistic is not fp

Definition at line 110 of file observation.cc.

References getFloat(), and setValue().

+ Here is the call graph for this function:

◆ addValue() [3/4]

void isc::stats::Observation::addValue ( const StatsDuration value)

Records incremental duration observation.

Parameters
valueduration value observed
Exceptions
InvalidStatTypeif statistic is not time duration

Definition at line 115 of file observation.cc.

References getDuration(), and setValue().

+ Here is the call graph for this function:

◆ addValue() [4/4]

void isc::stats::Observation::addValue ( const std::string &  value)

Records incremental string observation.

Parameters
valuestring value observed
Exceptions
InvalidStatTypeif statistic is not a string

Definition at line 120 of file observation.cc.

References getString(), and setValue().

+ Here is the call graph for this function:

◆ getDuration()

DurationSample isc::stats::Observation::getDuration ( ) const

Returns observed duration sample.

Returns
observed sample (value + timestamp)
Exceptions
InvalidStatTypeif statistic is not time duration

Definition at line 230 of file observation.cc.

References STAT_DURATION.

Referenced by addValue().

◆ getDurations()

std::list< DurationSample > isc::stats::Observation::getDurations ( ) const

Returns observed duration samples.

Returns
list of observed samples (value + timestamp)
Exceptions
InvalidStatTypeif statistic is not time duration

Definition at line 263 of file observation.cc.

References STAT_DURATION.

Referenced by getJSON().

◆ getFloat()

FloatSample isc::stats::Observation::getFloat ( ) const

Returns observed float sample.

Returns
observed sample (value + timestamp)
Exceptions
InvalidStatTypeif statistic is not fp

Definition at line 226 of file observation.cc.

References STAT_FLOAT.

Referenced by addValue().

◆ getFloats()

std::list< FloatSample > isc::stats::Observation::getFloats ( ) const

Returns observed float samples.

Returns
list of observed samples (value + timestamp)
Exceptions
InvalidStatTypeif statistic is not fp

Definition at line 259 of file observation.cc.

References STAT_FLOAT.

Referenced by getJSON().

◆ getInteger()

IntegerSample isc::stats::Observation::getInteger ( ) const

Returns observed integer sample.

Returns
observed sample (value + timestamp)
Exceptions
InvalidStatTypeif statistic is not integer

Definition at line 222 of file observation.cc.

References STAT_INTEGER.

Referenced by addValue().

◆ getIntegers()

std::list< IntegerSample > isc::stats::Observation::getIntegers ( ) const

Returns observed integer samples.

Returns
list of observed samples (value + timestamp)
Exceptions
InvalidStatTypeif statistic is not integer

Definition at line 255 of file observation.cc.

References STAT_INTEGER.

Referenced by getJSON().

◆ getJSON()

isc::data::ConstElementPtr isc::stats::Observation::getJSON ( ) const

Returns as a JSON structure.

Returns
JSON structures representing all observations

Definition at line 391 of file observation.cc.

References isc::util::clockToText(), isc::data::Element::create(), isc::data::Element::createList(), isc::util::durationToText(), getDurations(), getFloats(), getIntegers(), getStrings(), isc_throw, STAT_DURATION, STAT_FLOAT, STAT_INTEGER, STAT_STRING, and typeToText().

+ Here is the call graph for this function:

◆ getMaxSampleAge()

std::pair< bool, StatsDuration > isc::stats::Observation::getMaxSampleAge ( ) const

Returns both values of max_sample_age_ of statistic.

Returns
max_sample_age_.

Definition at line 167 of file observation.cc.

◆ getMaxSampleAgeDefault()

const StatsDuration & isc::stats::Observation::getMaxSampleAgeDefault ( )
static

Get default maximum age of samples.

Returns
default maximum age of samples to keep.

Definition at line 355 of file observation.cc.

◆ getMaxSampleCount()

std::pair< bool, uint32_t > isc::stats::Observation::getMaxSampleCount ( ) const

Returns both values of max_sample_count_ of statistic.

Returns
max_sample_count_.

Definition at line 171 of file observation.cc.

References isc_throw, and typeToText().

+ Here is the call graph for this function:

◆ getMaxSampleCountDefault()

uint32_t isc::stats::Observation::getMaxSampleCountDefault ( )
static

Get default maximum count of samples.

Returns
max_samples default maximum count of samples to keep. (0 means that count limit was disabled)

Definition at line 359 of file observation.cc.

◆ getName()

std::string isc::stats::Observation::getName ( ) const
inline

Returns observation name.

Definition at line 305 of file observation.h.

References name_.

◆ getSize()

size_t isc::stats::Observation::getSize ( ) const

Returns size of observed storage.

Returns
size of storage

Definition at line 141 of file observation.cc.

References isc_throw, STAT_DURATION, STAT_FLOAT, STAT_INTEGER, STAT_STRING, and typeToText().

+ Here is the call graph for this function:

◆ getString()

StringSample isc::stats::Observation::getString ( ) const

Returns observed string sample.

Returns
observed sample (value + timestamp)
Exceptions
InvalidStatTypeif statistic is not a string

Definition at line 234 of file observation.cc.

References isc_throw, STAT_STRING, and typeToText().

Referenced by addValue().

+ Here is the call graph for this function:

◆ getStrings()

std::list< StringSample > isc::stats::Observation::getStrings ( ) const

Returns observed string samples.

Returns
list of observed samples (value + timestamp)
Exceptions
InvalidStatTypeif statistic is not a string

Definition at line 267 of file observation.cc.

References isc_throw, STAT_STRING, and typeToText().

Referenced by getJSON().

+ Here is the call graph for this function:

◆ getType()

Type isc::stats::Observation::getType ( ) const
inline

Returns statistic type.

Returns
statistic type

Definition at line 252 of file observation.h.

◆ reset()

void isc::stats::Observation::reset ( )

Resets statistic.

Sets statistic to a neutral (0, 0.0 or "") value and clears the underlying storage.

Definition at line 477 of file observation.cc.

References isc_throw, setValue(), STAT_DURATION, STAT_FLOAT, STAT_INTEGER, STAT_STRING, and typeToText().

+ Here is the call graph for this function:

◆ setMaxSampleAge()

void isc::stats::Observation::setMaxSampleAge ( const StatsDuration duration)

Determines maximum age of samples.

Specifies that statistic name should be stored not as a single value, but rather as a set of values. The duration determines the timespan. Samples older than duration will be discarded. This is time-constrained approach. For sample count constrained approach, see setMaxSampleCount() below.

Parameters
durationdetermines maximum age of samples Example: To set a statistic to keep observations for the last 5 minutes, call: setMaxSampleAge(std::chrono::minutes(5)); To revert statistic to a single value, call: setMaxSampleAge(StatsDuration::zero());

Definition at line 57 of file observation.cc.

References isc_throw, STAT_DURATION, STAT_FLOAT, STAT_INTEGER, STAT_STRING, and typeToText().

+ Here is the call graph for this function:

◆ setMaxSampleAgeDefault()

void isc::stats::Observation::setMaxSampleAgeDefault ( const StatsDuration duration)
static

Determines default maximum age of samples.

Parameters
durationdefault maximum age of samples to keep.

Definition at line 336 of file observation.cc.

◆ setMaxSampleCount()

void isc::stats::Observation::setMaxSampleCount ( uint32_t  max_samples)

Determines how many samples of a given statistic should be kept.

Specifies that statistic name should be stored not as a single value, but rather as a set of values. In this form, at most max_samples will be kept. When adding max_samples + 1 sample, the oldest sample will be discarded.

Parameters
max_sampleshow many samples of a given statistic should be kept Example: To set a statistic to keep the last 100 observations, call: setMaxSampleCount(100);

Definition at line 81 of file observation.cc.

References isc_throw, STAT_DURATION, STAT_FLOAT, STAT_INTEGER, STAT_STRING, and typeToText().

+ Here is the call graph for this function:

◆ setMaxSampleCountDefault()

void isc::stats::Observation::setMaxSampleCountDefault ( uint32_t  max_samples)
static

Determines default maximum count of samples.

Parameters
max_samplesdefault maximum count of samples to keep. (0 means to disable count limit and enable age limit)

Definition at line 341 of file observation.cc.

◆ setValue() [1/4]

void isc::stats::Observation::setValue ( const int64_t  value)

@

Records absolute integer observation

Parameters
valueinteger value observed
Exceptions
InvalidStatTypeif statistic is not integer

Definition at line 125 of file observation.cc.

References STAT_INTEGER.

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

◆ setValue() [2/4]

void isc::stats::Observation::setValue ( const double  value)

Records absolute floating point observation.

Parameters
valuefloating point value observed
Exceptions
InvalidStatTypeif statistic is not fp

Definition at line 129 of file observation.cc.

References STAT_FLOAT.

◆ setValue() [3/4]

void isc::stats::Observation::setValue ( const StatsDuration value)

Records absolute duration observation.

Parameters
valueduration value observed
Exceptions
InvalidStatTypeif statistic is not time duration

Definition at line 133 of file observation.cc.

References STAT_DURATION.

◆ setValue() [4/4]

void isc::stats::Observation::setValue ( const std::string &  value)

Records absolute string observation.

Parameters
valuestring value observed
Exceptions
InvalidStatTypeif statistic is not a string

Definition at line 137 of file observation.cc.

References STAT_STRING.

◆ typeToText()

std::string isc::stats::Observation::typeToText ( Type  type)
static

Converts statistic type to string.

Returns
textual name of statistic type

Definition at line 367 of file observation.cc.

References STAT_DURATION, STAT_FLOAT, STAT_INTEGER, and STAT_STRING.

Referenced by getJSON(), getMaxSampleCount(), getSize(), getString(), getStrings(), reset(), setMaxSampleAge(), and setMaxSampleCount().


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