Current File : //backups/router/usr/local/include/kea/stats/observation.h
// Copyright (C) 2015-2023 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
#ifndef OBSERVATION_H
#define OBSERVATION_H
#include <cc/data.h>
#include <exceptions/exceptions.h>
#include <util/bigints.h>
#include <boost/shared_ptr.hpp>
#include <chrono>
#include <list>
#include <stdint.h>
namespace isc {
namespace stats {
/// @brief Exception thrown if invalid statistic type is used
///
/// For example statistic is of type duration, but methods using
/// it as integer are called.
class InvalidStatType : public Exception {
public:
InvalidStatType(const char* file, size_t line, const char* what) :
isc::Exception(file, line, what) {}
};
/// @brief Define clock type.
///
/// @note: we use the system clock i.e. the wall clock because this
/// clock can be converted from and to standard Unix time (time_t).
typedef std::chrono::system_clock SampleClock;
/// @brief Defines duration type.
///
/// @note: the precision depends on the system,
typedef std::chrono::system_clock::duration StatsDuration;
/// @brief Returns the number of seconds in a duration.
///
/// @param dur The duration.
/// @return The number of seconds in the given duration.
inline long toSeconds(const StatsDuration& dur) {
return ((std::chrono::duration_cast<std::chrono::seconds>(dur)).count());
}
/// @defgroup stat_samples Specifies supported observation types.
///
/// @brief The list covers all supported types of observations.
///
/// @{
/// @brief Integer (implemented as signed 64-bit integer)
typedef std::pair<int64_t, SampleClock::time_point> IntegerSample;
/// @brief BigInteger (implemented as signed 128-bit integer)
typedef std::pair<isc::util::int128_t, SampleClock::time_point> BigIntegerSample;
/// @brief Float (implemented as double precision)
typedef std::pair<double, SampleClock::time_point> FloatSample;
/// @brief Time Duration
typedef std::pair<StatsDuration, SampleClock::time_point> DurationSample;
/// @brief String
typedef std::pair<std::string, SampleClock::time_point> StringSample;
/// @}
/// @brief 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 @ref getInteger, @ref getFloat,
/// @ref getDuration, @ref getString (appropriate type must be used) or
/// @ref getJSON, which is generic and can be used for all types.
///
/// Since Kea 1.6 multiple samples are stored for the same observation.
class Observation {
public:
/// @brief 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.
enum Type {
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
};
/// @brief Constructor for integer observations
///
/// @param name observation name
/// @param value integer value observed.
Observation(const std::string& name, const int64_t value);
/// @brief Constructor for big integer observations
///
/// @param name observation name
/// @param value integer value observed.
Observation(const std::string& name, const isc::util::int128_t& value);
/// @brief Constructor for floating point observations
///
/// @param name observation name
/// @param value floating point value observed.
Observation(const std::string& name, const double value);
/// @brief Constructor for duration observations
///
/// @param name observation name
/// @param value duration observed.
Observation(const std::string& name, const StatsDuration& value);
/// @brief Constructor for string observations
///
/// @param name observation name
/// @param value string observed.
Observation(const std::string& name, const std::string& value);
/// @brief 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 @ref
/// setMaxSampleCount() below.
///
///
/// @param 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());
void setMaxSampleAge(const StatsDuration& duration);
/// @brief 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.
///
///
/// @param 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);
void setMaxSampleCount(uint32_t max_samples);
/// @brief Determines default maximum age of samples.
///
/// @param duration default maximum age of samples to keep.
static void setMaxSampleAgeDefault(const StatsDuration& duration);
/// @brief Determines default maximum count of samples.
///
/// @param max_samples default maximum count of samples to keep.
/// (0 means to disable count limit and enable age limit)
static void setMaxSampleCountDefault(uint32_t max_samples);
/// @brief Get default maximum age of samples.
///
/// @return default maximum age of samples to keep.
static const StatsDuration& getMaxSampleAgeDefault();
/// @brief Get default maximum count of samples.
///
/// @return max_samples default maximum count of samples to keep.
/// (0 means that count limit was disabled)
static uint32_t getMaxSampleCountDefault();
/// @
/// @brief Records absolute integer observation
///
/// @param value integer value observed
/// @throw InvalidStatType if statistic is not integer
void setValue(const int64_t value);
/// @brief Records big integer observation
///
/// @param value integer value observed
/// @throw InvalidStatType if statistic is not integer
void setValue(const isc::util::int128_t& value);
/// @brief Records absolute floating point observation
///
/// @param value floating point value observed
/// @throw InvalidStatType if statistic is not fp
void setValue(const double value);
/// @brief Records absolute duration observation
///
/// @param value duration value observed
/// @throw InvalidStatType if statistic is not time duration
void setValue(const StatsDuration& value);
/// @brief Records absolute string observation
///
/// @param value string value observed
/// @throw InvalidStatType if statistic is not a string
void setValue(const std::string& value);
/// @brief Records incremental integer observation
///
/// @param value integer value observed
/// @throw InvalidStatType if statistic is not integer
void addValue(const int64_t value);
/// @brief Records incremental integer observation
///
/// @param value integer value observed
/// @throw InvalidStatType if statistic is not integer
void addValue(const isc::util::int128_t& value);
/// @brief Records incremental floating point observation
///
/// @param value floating point value observed
/// @throw InvalidStatType if statistic is not fp
void addValue(const double value);
/// @brief Records incremental duration observation
///
/// @param value duration value observed
/// @throw InvalidStatType if statistic is not time duration
void addValue(const StatsDuration& value);
/// @brief Records incremental string observation.
///
/// @param value string value observed
/// @throw InvalidStatType if statistic is not a string
void addValue(const std::string& value);
/// @brief Returns size of observed storage
///
/// @return size of storage
size_t getSize() const;
/// @brief Returns both values of max_sample_age_ of statistic.
///
/// @return max_sample_age_.
std::pair<bool, StatsDuration> getMaxSampleAge() const;
/// @brief Returns both values of max_sample_count_ of statistic.
///
/// @return max_sample_count_.
std::pair<bool, uint32_t> getMaxSampleCount() const;
/// @brief Resets statistic.
///
/// Sets statistic to a neutral (0, 0.0 or "") value and
/// clears the underlying storage.
void reset();
/// @brief Returns statistic type
/// @return statistic type
Type getType() const {
return (type_);
}
/// @brief Returns observed integer sample
/// @return observed sample (value + timestamp)
/// @throw InvalidStatType if statistic is not integer
IntegerSample getInteger() const;
/// @brief Returns observed integer sample
/// @return observed sample (value + timestamp)
/// @throw InvalidStatType if statistic is not integer
BigIntegerSample getBigInteger() const;
/// @brief Returns observed float sample
/// @return observed sample (value + timestamp)
/// @throw InvalidStatType if statistic is not fp
FloatSample getFloat() const;
/// @brief Returns observed duration sample
/// @return observed sample (value + timestamp)
/// @throw InvalidStatType if statistic is not time duration
DurationSample getDuration() const;
/// @brief Returns observed string sample
/// @return observed sample (value + timestamp)
/// @throw InvalidStatType if statistic is not a string
StringSample getString() const;
/// @brief Returns observed integer samples
/// @return list of observed samples (value + timestamp)
/// @throw InvalidStatType if statistic is not integer
std::list<IntegerSample> getIntegers() const;
/// @brief Returns observed big-integer samples
/// @return list of observed samples (value + timestamp)
/// @throw InvalidStatType if statistic is not integer
std::list<BigIntegerSample> getBigIntegers() const;
/// @brief Returns observed float samples
/// @return list of observed samples (value + timestamp)
/// @throw InvalidStatType if statistic is not fp
std::list<FloatSample> getFloats() const;
/// @brief Returns observed duration samples
/// @return list of observed samples (value + timestamp)
/// @throw InvalidStatType if statistic is not time duration
std::list<DurationSample> getDurations() const;
/// @brief Returns observed string samples
/// @return list of observed samples (value + timestamp)
/// @throw InvalidStatType if statistic is not a string
std::list<StringSample> getStrings() const;
/// @brief Returns as a JSON structure
/// @return JSON structures representing all observations
isc::data::ConstElementPtr getJSON() const;
/// @brief Converts statistic type to string
/// @return textual name of statistic type
static std::string typeToText(Type type);
/// @brief Returns observation name
std::string getName() const {
return (name_);
}
private:
/// @brief Returns size of observed storage
///
/// This method returns size of observed storage.
/// It is used by public methods to return size of
/// available storages.
/// @tparam Storage type of storage (e.g. list<IntegerSample>)
/// @param storage storage which size will be returned
/// @param exp_type expected observation type (used for sanity checking)
/// @return size of storage
template<typename StorageType>
size_t getSizeInternal(StorageType& storage, Type exp_type) const;
/// @brief Records absolute sample (internal version)
///
/// This method records an absolute value of an observation.
/// It is used by public methods to add sample to one of
/// available storages.
///
/// @tparam SampleType type of sample (e.g. IntegerSample)
/// @tparam StorageType type of storage (e.g. list<IntegerSample>)
/// @param value observation to be recorded
/// @param storage observation will be stored here
/// @param exp_type expected observation type (used for sanity checking)
/// @throw InvalidStatType if observation type mismatches
template<typename SampleType, typename StorageType>
void setValueInternal(SampleType value, StorageType& storage,
Type exp_type);
/// @brief Returns a sample (internal version)
///
/// @tparam SampleType type of sample (e.g. IntegerSample)
/// @tparam StorageType type of storage (e.g. list<IntegerSample>)
/// @param observation storage
/// @param exp_type expected observation type (used for sanity checking)
/// @throw InvalidStatType if observation type mismatches
/// @return Observed sample
template<typename SampleType, typename Storage>
SampleType getValueInternal(Storage& storage, Type exp_type) const;
/// @brief Returns samples (internal version)
///
/// @tparam SampleType type of samples (e.g. IntegerSample)
/// @tparam Storage type of storage (e.g. list<IntegerSample>)
/// @param observation storage
/// @param exp_type expected observation type (used for sanity checking)
/// @throw InvalidStatType if observation type mismatches
/// @return list of observed samples
template<typename SampleType, typename Storage>
std::list<SampleType> getValuesInternal(Storage& storage,
Type exp_type) const;
/// @brief Determines maximum age of samples.
///
/// @tparam Storage type of storage (e.g. list<IntegerSample>)
/// @param storage storage on which limit will be set
/// @param duration determines maximum age of samples
/// @param exp_type expected observation type (used for sanity checking)
template<typename StorageType>
void setMaxSampleAgeInternal(StorageType& storage,
const StatsDuration& duration, Type exp_type);
/// @brief Determines how many samples of a given statistic should be kept.
///
/// @tparam Storage type of storage (e.g. list<IntegerSample>)
/// @param storage storage on which limit will be set
/// @param max_samples determines maximum number of samples
/// @param exp_type expected observation type (used for sanity checking)
template<typename StorageType>
void setMaxSampleCountInternal(StorageType& storage,
uint32_t max_samples, Type exp_type);
/// @brief Observation (statistic) name
std::string name_;
/// @brief Observation (statistic) type)
Type type_;
/// @brief Maximum number of samples
/// The limit is represented as a pair
/// of bool value and uint32_t
/// Only one kind of limit can be active
/// The bool value informs which limit
/// is available
/// True means active limit, false means inactive limit
std::pair<bool, uint32_t> max_sample_count_;
/// @brief Default maximum number of samples
///
/// By default the MaxSampleCount is set to 20
/// and MaxSampleAge is disabled
static std::pair<bool, uint32_t> default_max_sample_count_;
/// @brief Maximum timespan of samples
/// The limit is represented as a pair
/// of bool value and StatsDuration
/// Only one kind of limit can be active
/// The bool value informs which limit
/// is available
/// True means active limit, false means inactive limit
std::pair<bool, StatsDuration> max_sample_age_;
/// @brief Default maximum timespan of samples
///
/// By default the MaxSampleCount is set to 20
/// and MaxSampleAge is disabled
static std::pair<bool, StatsDuration> default_max_sample_age_;
/// @defgroup samples_storage Storage for supported observations
///
/// @brief The following containers serve as a storage for all supported
/// observation types.
///
/// @{
/// @brief Storage for integer samples
std::list<IntegerSample> integer_samples_;
/// @brief Storage for big integer samples
std::list<BigIntegerSample> big_integer_samples_;
/// @brief Storage for floating point samples
std::list<FloatSample> float_samples_;
/// @brief Storage for time duration samples
std::list<DurationSample> duration_samples_;
/// @brief Storage for string samples
std::list<StringSample> string_samples_;
/// @}
};
/// @brief Observation pointer
typedef boost::shared_ptr<Observation> ObservationPtr;
}
}
#endif // OBSERVATION_H
Mini Shell