Kea: isc::stats::Observation Class Reference

| Kea 3.0.0

isc::stats::Observation Class Reference

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

`#include <observation.h>`

## Public Types
enum | Type { STAT_INTEGER , STAT_BIG_INTEGER , STAT_FLOAT , STAT_DURATION , STAT_STRING }
| Type of available statistics. More...

## Public Member Functions
| Observation (const std::string &name, const double value)
| Constructor for floating point observations.
| Observation (const std::string &name, const int64_t value)
| Constructor for integer observations.
| Observation (const std::string &name, const isc::util::int128_t &value)
| Constructor for big integer observations.
| Observation (const std::string &name, const StatsDuration &value)
| Constructor for duration observations.
| Observation (const std::string &name, const std::string &value)
| Constructor for string observations.
void | addValue (const double value)
| Records incremental floating point observation.
void | addValue (const int64_t value)
| Records incremental integer observation.
void | addValue (const isc::util::int128_t &value)
| Records incremental integer observation.
void | addValue (const StatsDuration &value)
| Records incremental duration observation.
void | addValue (const std::string &value)
| Records incremental string observation.
BigIntegerSample | getBigInteger () const
| Returns observed integer sample.
std::list< BigIntegerSample > | getBigIntegers () const
| Returns observed big-integer samples.
DurationSample | getDuration () const
| Returns observed duration sample.
std::list< DurationSample > | getDurations () const
| Returns observed duration samples.
FloatSample | getFloat () const
| Returns observed float sample.
std::list< FloatSample > | getFloats () const
| Returns observed float samples.
IntegerSample | getInteger () const
| Returns observed integer sample.
std::list< IntegerSample > | getIntegers () const
| Returns observed integer samples.
isc::data::ConstElementPtr | getJSON () const
| Returns as a JSON structure.
std::pair< bool, StatsDuration > | getMaxSampleAge () const
| Returns both values of max_sample_age_ of statistic.
std::pair< bool, uint32_t > | getMaxSampleCount () const
| Returns both values of max_sample_count_ of statistic.
std::string | getName () const
| Returns observation name.
size_t | getSize () const
| Returns size of observed storage.
StringSample | getString () const
| Returns observed string sample.
std::list< StringSample > | getStrings () const
| Returns observed string samples.
Type | getType () const
| Returns statistic type.
void | reset ()
| Resets statistic.
void | setMaxSampleAge (const StatsDuration &duration)
| Determines maximum age of samples.
void | setMaxSampleCount (uint32_t max_samples)
| Determines how many samples of a given statistic should be kept.
void | setValue (const double value)
| Records absolute floating point observation.
void | setValue (const int64_t value)
| @
void | setValue (const isc::util::int128_t &value)
| Records big integer observation.
void | setValue (const StatsDuration &value)
| Records absolute duration observation.
void | setValue (const std::string &value)
| Records absolute string observation.

## Static Public Member Functions
static const StatsDuration & | getMaxSampleAgeDefault ()
| Get default maximum age of samples.
static uint32_t | getMaxSampleCountDefault ()
| Get default maximum count of samples.
static void | setMaxSampleAgeDefault (const StatsDuration &duration)
| Determines default maximum age of samples.
static void | setMaxSampleCountDefault (uint32_t max_samples)
| Determines default maximum count of samples.
static std::string | typeToText (Type type)
| Converts statistic type to string.

## 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 91 of file observation.h.

## Member Enumeration Documentation

## ◆ Type

enum isc::stats::Observation::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 signed 64-bit integer value
STAT_BIG_INTEGER | this statistic is signed 128-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 102 of file observation.h.

## Constructor & Destructor Documentation

## ◆ Observation() [1/5]

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

Constructor for integer observations.

Parameters

  name | observation name
  value | integer value observed.

Definition at line 31 of file observation.cc.

References setValue(), and STAT_INTEGER.

Here is the call graph for this function:

## ◆ Observation() [2/5]

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

Constructor for big integer observations.

Parameters

  name | observation name
  value | integer value observed.

Definition at line 38 of file observation.cc.

References setValue(), and STAT_BIG_INTEGER.

Here is the call graph for this function:

## ◆ Observation() [3/5]

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

Constructor for floating point observations.

Parameters

  name | observation name
  value | floating point value observed.

Definition at line 45 of file observation.cc.

References setValue(), and STAT_FLOAT.

Here is the call graph for this function:

## ◆ Observation() [4/5]

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

Constructor for duration observations.

Parameters

  name | observation name
  value | duration observed.

Definition at line 52 of file observation.cc.

References setValue(), and STAT_DURATION.

Here is the call graph for this function:

## ◆ Observation() [5/5]

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

Constructor for string observations.

Parameters

  name | observation name
  value | string observed.

Definition at line 59 of file observation.cc.

References setValue(), and STAT_STRING.

Here is the call graph for this function:

## Member Function Documentation

## ◆ addValue() [1/5]

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

Records incremental floating point observation.

Parameters

  value | floating point value observed

Exceptions

  InvalidStatType | if statistic is not fp

Definition at line 132 of file observation.cc.

References getFloat(), and setValue().

Here is the call graph for this function:

## ◆ addValue() [2/5]

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

Records incremental integer observation.

Parameters

  value | integer value observed

Exceptions

  InvalidStatType | if statistic is not integer

Definition at line 122 of file observation.cc.

References getInteger(), and setValue().

Here is the call graph for this function:

## ◆ addValue() [3/5]

void isc::stats::Observation::addValue | ( | const isc::util::int128_t & | value | ) |

Records incremental integer observation.

Parameters

  value | integer value observed

Exceptions

  InvalidStatType | if statistic is not integer

Definition at line 127 of file observation.cc.

References getBigInteger(), and setValue().

Here is the call graph for this function:

## ◆ addValue() [4/5]

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

Records incremental duration observation.

Parameters

  value | duration value observed

Exceptions

  InvalidStatType | if statistic is not time duration

Definition at line 137 of file observation.cc.

References getDuration(), and setValue().

Here is the call graph for this function:

## ◆ addValue() [5/5]

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

Records incremental string observation.

Parameters

  value | string value observed

Exceptions

  InvalidStatType | if statistic is not a string

Definition at line 142 of file observation.cc.

References getString(), and setValue().

Here is the call graph for this function:

## ◆ getBigInteger()

BigIntegerSample isc::stats::Observation::getBigInteger | ( |  | ) | const

Returns observed integer sample.

Returns
  observed sample (value + timestamp)

Exceptions

  InvalidStatType | if statistic is not integer

Definition at line 256 of file observation.cc.

References STAT_BIG_INTEGER.

Referenced by addValue().

## ◆ getBigIntegers()

std::list< BigIntegerSample > isc::stats::Observation::getBigIntegers | ( |  | ) | const

Returns observed big-integer samples.

Returns
  list of observed samples (value + timestamp)

Exceptions

  InvalidStatType | if statistic is not integer

Definition at line 293 of file observation.cc.

References STAT_BIG_INTEGER.

Referenced by getJSON().

## ◆ getDuration()

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

Returns observed duration sample.

Returns
  observed sample (value + timestamp)

Exceptions

  InvalidStatType | if statistic is not time duration

Definition at line 264 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

  InvalidStatType | if statistic is not time duration

Definition at line 301 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

  InvalidStatType | if statistic is not fp

Definition at line 260 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

  InvalidStatType | if statistic is not fp

Definition at line 297 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

  InvalidStatType | if statistic is not integer

Definition at line 252 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

  InvalidStatType | if statistic is not integer

Definition at line 289 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 432 of file observation.cc.

References isc::util::clockToText(), isc::data::Element::create(), isc::data::Element::createList(), isc::util::durationToText(), getBigIntegers(), getDurations(), getFloats(), getIntegers(), getStrings(), isc_throw, STAT_BIG_INTEGER, 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 197 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 393 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 201 of file observation.cc.

## ◆ 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 397 of file observation.cc.

## ◆ getName()

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

Returns observation name.

Definition at line 341 of file observation.h.

## ◆ getSize()

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

Returns size of observed storage.

Returns
  size of storage

Definition at line 167 of file observation.cc.

References isc_throw, STAT_BIG_INTEGER, 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

  InvalidStatType | if statistic is not a string

Definition at line 268 of file observation.cc.

References STAT_STRING.

Referenced by addValue().

## ◆ getStrings()

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

Returns observed string samples.

Returns
  list of observed samples (value + timestamp)

Exceptions

  InvalidStatType | if statistic is not a string

Definition at line 305 of file observation.cc.

References STAT_STRING.

Referenced by getJSON().

## ◆ getType()

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

Returns statistic type.

Returns
  statistic type

Definition at line 278 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 534 of file observation.cc.

References isc_throw, setValue(), STAT_BIG_INTEGER, 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

  duration | determines 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 66 of file observation.cc.

References isc_throw, STAT_BIG_INTEGER, 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

  duration | default maximum age of samples to keep.

Definition at line 374 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_samples | how 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 94 of file observation.cc.

References isc_throw, STAT_BIG_INTEGER, 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_samples | default maximum count of samples to keep. (0 means to disable count limit and enable age limit)

Definition at line 379 of file observation.cc.

## ◆ setValue() [1/5]

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

Records absolute floating point observation.

Parameters

  value | floating point value observed

Exceptions

  InvalidStatType | if statistic is not fp

Definition at line 155 of file observation.cc.

References STAT_FLOAT.

## ◆ setValue() [2/5]

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

@

Records absolute integer observation

Parameters

  value | integer value observed

Exceptions

  InvalidStatType | if statistic is not integer

Definition at line 147 of file observation.cc.

References STAT_INTEGER.

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

## ◆ setValue() [3/5]

void isc::stats::Observation::setValue | ( | const isc::util::int128_t & | value | ) |

Records big integer observation.

Parameters

  value | integer value observed

Exceptions

  InvalidStatType | if statistic is not integer

Definition at line 151 of file observation.cc.

References STAT_BIG_INTEGER.

## ◆ setValue() [4/5]

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

Records absolute duration observation.

Parameters

  value | duration value observed

Exceptions

  InvalidStatType | if statistic is not time duration

Definition at line 159 of file observation.cc.

References STAT_DURATION.

## ◆ setValue() [5/5]

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

Records absolute string observation.

Parameters

  value | string value observed

Exceptions

  InvalidStatType | if statistic is not a string

Definition at line 163 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 405 of file observation.cc.

References STAT_BIG_INTEGER, STAT_DURATION, STAT_FLOAT, STAT_INTEGER, and STAT_STRING.

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

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

- observation.h
- observation.cc