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

#include <perfmon_mgr.h>

Inheritance diagram for isc::perfmon::PerfMonMgr:

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::SubnetPtr 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 init().

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 149 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(), isc::perfmon::PerfMonConfig::setEnableMonitoring(), and isc::Exception::what().

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 336 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 350 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 226 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 279 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::SubnetPtr	subnet )

Processes the event stack of a query packet.

Emit a dump of packet stack to perfmon debug log at detail level.
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().
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 189 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 216 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 167 of file perfmon_mgr.cc.

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

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

◆ 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:

Public Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ PerfMonMgr()

◆ ~PerfMonMgr()

Member Function Documentation

◆ addDurationSample()

◆ configure()

◆ formatDurationDataAsElements()

◆ formatDurationDataAsResultSet()

◆ getAlarmReportInterval()

◆ getDurationStore()

◆ getIntervalDuration()

◆ init()

◆ perfmonControlHandler()

◆ perfmonGetAllDurationsHandler()

◆ processPktEventStack()

◆ reportAlarm()

◆ reportTimerExpired()

◆ reportToStatsMgr()

◆ setNextReportExpiration()

Member Data Documentation

◆ alarm_report_interval_

◆ duration_store_

◆ interval_duration_

◆ io_service_

◆ mutex_

◆ report_timer_