Kea: isc::perfmon::PerfMonMgr Class Reference

| Kea 3.0.0

isc::perfmon::PerfMonMgr Class Reference

Singleton which provides overall configuration, control, and state of the PerfMon hook library. More...

`#include <perfmon_mgr.h>`

Inheritance diagram for isc::perfmon::PerfMonMgr:
[legend]

## Public Member Functions
| PerfMonMgr (uint16_t family)
| Constructor.
virtual | ~PerfMonMgr ()=default
| Destructor.
void | addDurationSample (DurationKeyPtr key, const Duration &sample)
| Adds a duration sample to a MonitoredDuration.
void | configure (const isc::data::ConstElementPtr &params)
| Parses the hook library 'parameters' element.
data::ElementPtr | formatDurationDataAsElements (MonitoredDurationCollectionPtr durations) const
| Renders a list of MonitoredDurations as a map of individual Elements.
data::ElementPtr | formatDurationDataAsResultSet (MonitoredDurationCollectionPtr durations) const
| Renders a list of MonitoredDurations as a result set.
Duration | getAlarmReportInterval ()
| Get the alarm report interval.
MonitoredDurationStorePtr | getDurationStore ()
| Get the duration store.
Duration | getIntervalDuration ()
| Get the interval duration.
virtual void | init ()
| Sets convenience values and (re)creates the duration store.
int | perfmonControlHandler (hooks::CalloutHandle &handle)
| perfmon-control command handler
int | perfmonGetAllDurationsHandler (hooks::CalloutHandle &handle)
| perfmon-get-all-durations handler
void | processPktEventStack (isc::dhcp::PktPtr query, isc::dhcp::PktPtr response, const isc::dhcp::ConstSubnetPtr subnet)
| Processes the event stack of a query packet.
void | reportAlarm (AlarmPtr alarm, const Duration &mean)
| Emits a report for a given alarm.
void | reportTimerExpired ()
| Handler invoked when the report timer expires.
Duration | reportToStatsMgr (MonitoredDurationPtr duration)
| Emits an entry to StatsMgr for a given duration.
void | setNextReportExpiration ()
| Updates the report timer.
Public Member Functions inherited from isc::perfmon::PerfMonConfig
| PerfMonConfig (uint16_t family)
| Constructor.
virtual | ~PerfMonConfig ()=default
| Destructor.
uint32_t | getAlarmReportSecs () const
| Fetches the value of alarm-report-secs.
AlarmStorePtr | getAlarmStore ()
| Get the alarm store.
bool | getEnableMonitoring () const
| Fetches the value of enable-monitoring.
uint16_t | getFamily ()
| Get protocol family.
uint32_t | getIntervalWidthSecs () const
| Fetches the value of interval-width-secs.
bool | getStatsMgrReporting () const
| Fetches the value of stats-mgr-reporting.
void | parse (data::ConstElementPtr config)
| Extracts member values from an Element::map.
void | parseAlarms (data::ConstElementPtr config)
| Re-creates the AlarmStore and populates it by parsing a list of alarm elements.
void | setAlarmReportSecs (uint32_t value)
| Sets the value of alarm-report-secs.
void | setEnableMonitoring (bool value)
| Sets the value of enable-monitoring.
void | setIntervalWidthSecs (uint32_t value)
| Sets the value of interval-width-secs.
void | setStatsMgrReporting (bool value)
| Sets the value of stats-mgr-reporting.

## Protected Attributes
Duration | alarm_report_interval_
| Length of time between raised Alarm reports.
MonitoredDurationStorePtr | duration_store_
| In-memory store of MonitoredDurations.
Duration | interval_duration_
| Length of time a MonitoredDuration accumulates samples until reporting.
asiolink::IOServicePtr | io_service_
| Tracks whether or not the server is processing DHCP packets.
const boost::scoped_ptr< std::mutex > | mutex_
| The mutex used to protect internal state.
asiolink::IntervalTimerPtr | report_timer_
| Timer which tracks the next duration due to report.
Protected Attributes inherited from isc::perfmon::PerfMonConfig
uint32_t | alarm_report_secs_
| Number of seconds between reports of a raised alarm.
AlarmStorePtr | alarm_store_
| Stores the configured alarms.
std::atomic< bool > | enable_monitoring_
| If true, performance data is processed/reported.
uint16_t | family_
| Protocol family AF_INET or AF_INET6.
uint32_t | interval_width_secs_
| Number of seconds a duration accumulates samples until reporting.
std::atomic< bool > | stats_mgr_reporting_
| If true durations report to StatsMgr at the end of each interval.

## Additional Inherited Members
Static Public Attributes inherited from isc::perfmon::PerfMonConfig
static const data::SimpleKeywords | CONFIG_KEYWORDS
| List of valid parameters and expected types.
static const data::SimpleDefaults | SIMPLE_DEFAULTS
| List of valid parameter defaults.

## Detailed Description

Singleton which provides overall configuration, control, and state of the PerfMon hook library.

It owns the MonitoredDurationStore and AlarmStore instances and supplies callout and command API handlers. It derives from PerfMonConfiga and CmdsImpl.

Definition at line 29 of file perfmon_mgr.h.

## Constructor & Destructor Documentation

## ◆ PerfMonMgr()

isc::perfmon::PerfMonMgr::PerfMonMgr | ( | uint16_t | family | ) |
| explicit

Constructor.

Parameters

  family | Protocol family AF_INET or AF_INET6.

Definition at line 31 of file perfmon_mgr.cc.

References isc::perfmon::PerfMonConfig::PerfMonConfig(), isc::perfmon::PerfMonConfig::family_, init(), and mutex_.

Here is the call graph for this function:

## ◆ ~PerfMonMgr()

virtual isc::perfmon::PerfMonMgr::~PerfMonMgr | ( |  | ) |
| virtualdefault

Destructor.

## Member Function Documentation

## ◆ addDurationSample()

void isc::perfmon::PerfMonMgr::addDurationSample | ( | DurationKeyPtr | key,
|  | const Duration & | sample )

Adds a duration sample to a MonitoredDuration.

The MonitoredDuration identified by the given key is fetched from the store and updated with the sample. If the update returns the duration this means it is time to report the duration via StatsMgr. The reported mean is then checked against an alarm, if one exists. If the check returns the alarm, then the alarm has undergone a reportable event and is passed to reporting.

Parameters

  key | identifies the duration to update.
  sample | amount of time that elapsed between the two events identified in the key.

Definition at line 150 of file perfmon_mgr.cc.

References alarm_report_interval_, isc::perfmon::PerfMonConfig::alarm_store_, duration_store_, reportAlarm(), and reportToStatsMgr().

Referenced by processPktEventStack().

Here is the call graph for this function:

## ◆ configure()

void isc::perfmon::PerfMonMgr::configure | ( | const isc::data::ConstElementPtr & | params | ) |

Parses the hook library 'parameters' element.

Parameters

  params | map of configuration parameters to parse.

Definition at line 47 of file perfmon_mgr.cc.

References init(), isc_throw, isc::data::Element::map, isc::perfmon::PerfMonConfig::parse(), and isc::perfmon::PerfMonConfig::setEnableMonitoring().

Here is the call graph for this function:

## ◆ formatDurationDataAsElements()

ElementPtr isc::perfmon::PerfMonMgr::formatDurationDataAsElements | ( | MonitoredDurationCollectionPtr | durations | ) | const

Renders a list of MonitoredDurations as a map of individual Elements.

Parameters

  durations | collection of durations to convert

Definition at line 337 of file perfmon_mgr.cc.

References isc::data::Element::createList().

Referenced by perfmonGetAllDurationsHandler().

Here is the call graph for this function:

## ◆ formatDurationDataAsResultSet()

ElementPtr isc::perfmon::PerfMonMgr::formatDurationDataAsResultSet | ( | MonitoredDurationCollectionPtr | durations | ) | const

Renders a list of MonitoredDurations as a result set.

The result set Element will be as shown below:

"durations-result-set": {
"columns": [
"subnet-id", "query-type", "response-type", "start-event", "end-event",
"interval start", "occurrences", "min-duration-usecs", "max-duration-usecs",
"total-duration-usecs"
],
"rows": [
[
10, "discover", "offer", "socket_received", "buffer_read",
"2024-01-18 10:11:19.498739", 105, 5300, 9000, 786500
],
..
]

Parameters

  durations | collection of durations to convert

Definition at line 351 of file perfmon_mgr.cc.

References isc::data::Element::createList(), isc::data::Element::createMap(), and isc::perfmon::MonitoredDuration::valueRowColumns().

Referenced by perfmonGetAllDurationsHandler().

Here is the call graph for this function:

## ◆ getAlarmReportInterval()

Duration isc::perfmon::PerfMonMgr::getAlarmReportInterval | ( |  | ) |
| inline

Get the alarm report interval.

Returns
  alarm-report-secs as a Duration.

Definition at line 273 of file perfmon_mgr.h.

References alarm_report_interval_.

## ◆ getDurationStore()

MonitoredDurationStorePtr isc::perfmon::PerfMonMgr::getDurationStore | ( |  | ) |
| inline

Get the duration store.

Returns
  pointer to the duration store.

Definition at line 280 of file perfmon_mgr.h.

References duration_store_.

## ◆ getIntervalDuration()

Duration isc::perfmon::PerfMonMgr::getIntervalDuration | ( |  | ) |
| inline

Get the interval duration.

Returns
  interval-width-secs as a Duration.

Definition at line 266 of file perfmon_mgr.h.

References interval_duration_.

## ◆ init()

void isc::perfmon::PerfMonMgr::init | ( |  | ) |
| virtual

Sets convenience values and (re)creates the duration store.

Called by the constructor and also by configure().

Definition at line 37 of file perfmon_mgr.cc.

References alarm_report_interval_, isc::perfmon::PerfMonConfig::alarm_report_secs_, duration_store_, isc::perfmon::PerfMonConfig::family_, interval_duration_, and isc::perfmon::PerfMonConfig::interval_width_secs_.

Referenced by PerfMonMgr(), and configure().

## ◆ perfmonControlHandler()

int isc::perfmon::PerfMonMgr::perfmonControlHandler | ( | hooks::CalloutHandle & | handle | ) |

perfmon-control command handler

This command sets enable-monitoring and/or stats-mgr-reporting (affects in memory value(s) only).

{
"command": "perfmon-control",
"arguments": {
"enable-monitoring": true,
"stats-mgr-reporting": true
}
}

It extracts the command name and arguments from the given CalloutHandle, attempts to process them, and then set's the handle's "response" arguments accordingly. Regardless of which arguments, if any, were specified the command will always return the new/current values for both settings.

"arguments": {
"enable-monitoring": true,
"stats-mgr-reporting": true
},
"result": 0,
"text": "perfmon-control success"
}

Parameters

  handle | Callout context - which is expected to contain the command JSON text in the "command" argument

Returns
  result of the operation

Definition at line 227 of file perfmon_mgr.cc.

References isc::data::Element::boolean, isc::data::SimpleParser::checkKeywords(), isc::config::CmdsImpl::cmd_args_, isc::config::CONTROL_RESULT_SUCCESS, isc::data::Element::create(), isc::config::createAnswer(), isc::data::Element::createMap(), isc::perfmon::PerfMonConfig::enable_monitoring_, isc::config::CmdsImpl::extractCommand(), LOG_ERROR, LOG_INFO, PERFMON_CMDS_CONTROL_ERROR, PERFMON_CMDS_CONTROL_OK, isc::perfmon::perfmon_logger, isc::config::CmdsImpl::setErrorResponse(), isc::config::CmdsImpl::setResponse(), and isc::perfmon::PerfMonConfig::stats_mgr_reporting_.

Here is the call graph for this function:

## ◆ perfmonGetAllDurationsHandler()

int isc::perfmon::PerfMonMgr::perfmonGetAllDurationsHandler | ( | hooks::CalloutHandle & | handle | ) |

perfmon-get-all-durations handler

This command fetches all of the monitored durations and their previous intervals (if one).

{
"command": "perfmon-get-all-durations",
"arguments": {
"result-set-format": true
}
}

It extracts the command name and arguments from the given CalloutHandle, attempts to process them, and then set's the handle's "response" arguments accordingly. If result-set-format is false (the default) the durations are returned as a list of Elements:

{
"result": 0,
"text": "perfmon-get-all-durations: n rows found",
"arguments": {
"result-set-format": false,
"interval-width-secs": 5,
"timestamp": "2024-01-18 10:11:20.594800"
"durations": [{
"duration-key": {
"query-type": "discover",
"response-type": "offer",
"start-event": "socket_received",
"stop-event": "buffer_read",
"subnet-id": 10
},
"start-time": "2024-01-18 10:11:19.498739",
"occurrences": 105,
"min-duration-usecs": 5300,
"max-duration-usecs": 9000,
"total-duration-usecs": 786500
},
..
]
},
}

If result-set-format is true, the durations are returned in a more compact format, patterned after an SQL result set:

{
"result": 0,
"text": "perfmon-get-all-durations: n rows found",
"arguments": {
"result-set-format": true,
"interval-width-secs": 5,
"timestamp": "2024-01-18 10:11:20.594800"
"durations-result-set": {
"columns": [
"subnet-id", "query-type", "response-type", "start-event", "end-event",
"interval start", "occurrences", "min-duration-usecs", "max-duration-usecs",
"total-duration-usecs"
],
"rows": [
[
10, "discover", "offer", "socket_received", "buffer_read",
"2024-01-18 10:11:19.498739", 105, 5300, 9000, 786500
],
..
]
}
}
}

Parameters

  handle | Callout context - which is expected to contain the command JSON text in the "command" argument

Returns
  result of the operation

Definition at line 280 of file perfmon_mgr.cc.

References isc::data::Element::boolean, isc::data::SimpleParser::checkKeywords(), isc::config::CmdsImpl::cmd_args_, isc::config::CONTROL_RESULT_EMPTY, isc::config::CONTROL_RESULT_SUCCESS, isc::data::Element::create(), isc::config::createAnswer(), isc::data::Element::createMap(), duration_store_, isc::config::CmdsImpl::extractCommand(), formatDurationDataAsElements(), formatDurationDataAsResultSet(), isc::perfmon::PerfMonConfig::getIntervalWidthSecs(), LOG_ERROR, LOG_INFO, isc::dhcp::PktEvent::now(), PERFMON_CMDS_GET_ALL_DURATIONS_ERROR, PERFMON_CMDS_GET_ALL_DURATIONS_OK, isc::perfmon::perfmon_logger, isc::util::ptimeToText(), isc::config::CmdsImpl::setErrorResponse(), and isc::config::CmdsImpl::setResponse().

Here is the call graph for this function:

## ◆ processPktEventStack()

void isc::perfmon::PerfMonMgr::processPktEventStack | ( | isc::dhcp::PktPtr | query,
|  | isc::dhcp::PktPtr | response,
|  | const isc::dhcp::ConstSubnetPtr | subnet )

Processes the event stack of a query packet.

1. Emit a dump of packet stack to perfmon debug log at detail level.
2. Iterates over the query's event stack creating a DurationKey for each adjacent event pair, computing the elapsed time between them and then calls addDurationSample().
3. Generates composite duration updates. Durations that monitor total response time for a given query/response pair will be computed using the first and last events in the stack, with a begin event label of "composite" and an end label of "total_response" for the DurationKey. These duration updates will be passed into addDurationSample(). Other composite durations may be added in the future.

Parameters

  query | query packet whose stack is to be processed.
  response | response packet generated for the query.
  subnet | selected subnet, if empty use the global subnet id.

Definition at line 71 of file perfmon_mgr.cc.

References addDurationSample(), isc::log::DBGLVL_TRACE_DETAIL, isc::dhcp::DHCP_NOTYPE, DHCPV6_NOTYPE, isc::perfmon::PerfMonConfig::enable_monitoring_, isc::perfmon::PerfMonConfig::family_, isc_throw, LOG_DEBUG, PERFMON_DHCP4_PKT_EVENTS, PERFMON_DHCP6_PKT_EVENTS, isc::perfmon::perfmon_logger, and isc::perfmon::DurationKey::validateMessagePair().

Here is the call graph for this function:

## ◆ reportAlarm()

void isc::perfmon::PerfMonMgr::reportAlarm | ( | AlarmPtr | alarm,
|  | const Duration & | mean )

Emits a report for a given alarm.

Emits a WARN log if the alarm state is TRIGGERED or an INFO log if it is CLEARED. This may expand in the future to accommodate additional reporting mechanisms.

Parameters

  alarm | Alarm to report.
  mean | Duration mean which caused the state transition.

Definition at line 190 of file perfmon_mgr.cc.

References isc::perfmon::PerfMonConfig::alarm_store_, isc::perfmon::Alarm::CLEAR, isc::perfmon::Alarm::DISABLED, LOG_INFO, LOG_WARN, PERFMON_ALARM_CLEARED, PERFMON_ALARM_TRIGGERED, isc::perfmon::perfmon_logger, isc::util::ptimeToText(), and isc::perfmon::Alarm::TRIGGERED.

Referenced by addDurationSample().

Here is the call graph for this function:

## ◆ reportTimerExpired()

void isc::perfmon::PerfMonMgr::reportTimerExpired | ( |  | ) |

Handler invoked when the report timer expires.

Fetches a list of the durations which are overdue to report and submits them for reporting.

Definition at line 217 of file perfmon_mgr.cc.

References isc_throw.

## ◆ reportToStatsMgr()

Duration isc::perfmon::PerfMonMgr::reportToStatsMgr | ( | MonitoredDurationPtr | duration | ) |

Emits an entry to StatsMgr for a given duration.

Calculates the mean duration for the reportable interval and reports the value to StatsMgr if stat-mgr-reporting is true.

Parameters

  duration | duration to report.

Returns
  Always returns the mean duration for reportable interval.

Todo
  - decide if we want to report min and max values too.

Definition at line 168 of file perfmon_mgr.cc.

References isc::perfmon::PerfMonConfig::getStatsMgrReporting(), isc::stats::StatsMgr::instance(), isc_throw, and isc::stats::StatsMgr::setValue().

Referenced by addDurationSample().

Here is the call graph for this function:

## ◆ setNextReportExpiration()

void isc::perfmon::PerfMonMgr::setNextReportExpiration | ( |  | ) |

Updates the report timer.

MonitoredDurationPtr next = durations->getReportsNext() if next reschedule report timer for (next->getIntervalStart() + interval_duration_); else cancel report timer

Definition at line 222 of file perfmon_mgr.cc.

References isc_throw.

## Member Data Documentation

## ◆ alarm_report_interval_

Duration isc::perfmon::PerfMonMgr::alarm_report_interval_
| protected

Length of time between raised Alarm reports.

It's a conversion of alarm-report-secs to a Duration set during configuration parsing.

Definition at line 291 of file perfmon_mgr.h.

Referenced by addDurationSample(), getAlarmReportInterval(), and init().

## ◆ duration_store_

MonitoredDurationStorePtr isc::perfmon::PerfMonMgr::duration_store_
| protected

In-memory store of MonitoredDurations.

Definition at line 294 of file perfmon_mgr.h.

Referenced by addDurationSample(), getDurationStore(), init(), and perfmonGetAllDurationsHandler().

## ◆ interval_duration_

Duration isc::perfmon::PerfMonMgr::interval_duration_
| protected

Length of time a MonitoredDuration accumulates samples until reporting.

Definition at line 286 of file perfmon_mgr.h.

Referenced by getIntervalDuration(), and init().

## ◆ io_service_

asiolink::IOServicePtr isc::perfmon::PerfMonMgr::io_service_
| protected

Tracks whether or not the server is processing DHCP packets.

Todo
  Not sure if we really care. When not in service, traffic will effectively stop. Any active durations will eventually report once via timer but nothing more until traffic resumes.

IOService instance used by the timer.

Definition at line 304 of file perfmon_mgr.h.

## ◆ mutex_

const boost::scoped_ptr<std::mutex> isc::perfmon::PerfMonMgr::mutex_
| protected

The mutex used to protect internal state.

Definition at line 310 of file perfmon_mgr.h.

Referenced by PerfMonMgr().

## ◆ report_timer_

asiolink::IntervalTimerPtr isc::perfmon::PerfMonMgr::report_timer_
| protected

Timer which tracks the next duration due to report.

Definition at line 307 of file perfmon_mgr.h.

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

- perfmon_mgr.h
- perfmon_mgr.cc