From: Thomas Markwalder Date: Wed, 12 Jun 2024 19:57:49 +0000 (-0400) Subject: [#3328] Doc updates X-Git-Tag: Kea-2.7.0~42 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6f9989b6d2fe9339777a70e875fe66cd32b75a51;p=thirdparty%2Fkea.git [#3328] Doc updates /doc/sphinx/api-files.txt /src/share/api/api_files.mk Added new command files src/share/api/perfmon-control.json src/share/api/perfmon-get-all-durations.json /doc/sphinx/arm/hooks-perfmon.rst Updated API section /src/hooks/dhcp/perfmon/perfmon_mgr.cc Added "result-set-format" to get-all-durations results. --- diff --git a/doc/sphinx/api-files.txt b/doc/sphinx/api-files.txt index 07c6e3d4ad..4e363d09b4 100644 --- a/doc/sphinx/api-files.txt +++ b/doc/sphinx/api-files.txt @@ -81,6 +81,8 @@ src/share/api/network6-get.json src/share/api/network6-list.json src/share/api/network6-subnet-add.json src/share/api/network6-subnet-del.json +src/share/api/perfmon-control.json +src/share/api/perfmon-get-all-durations.json src/share/api/remote-class4-del.json src/share/api/remote-class4-get-all.json src/share/api/remote-class4-get.json diff --git a/doc/sphinx/arm/hooks-perfmon.rst b/doc/sphinx/arm/hooks-perfmon.rst index 494c89f416..691961aaea 100644 --- a/doc/sphinx/arm/hooks-perfmon.rst +++ b/doc/sphinx/arm/hooks-perfmon.rst @@ -225,6 +225,10 @@ The alarm-cleared INFO log looks like this: API Commands ~~~~~~~~~~~~ +The ``perfmon-control`` Command +------------------------------- + +.. isccmd:: command-perfmon-control: .. _command-perfmon-control: This command can be used to enable or disable active monitoring and statistics @@ -240,7 +244,7 @@ reporting at runtime without altering or reloading configuration. } } -Regardless of the arguments (if any) are supplied, the current values of both +Regardless of the arguments (if any) supplied, the resulting values of both flags are always returned: :: @@ -254,8 +258,112 @@ flags are always returned: } } +The ``perfmon-get-all-durations`` Command +----------------------------------------- + +.. isccmd:: perfmon-get-all-durations: +.. _command-perfmon-get-all-durations: + +This command fetches all monitored duration data currently held in memory by +the Perfmon hook library. + +:: + + { + "command": "perfmon-get-all-durations", + "arguments": { + "result-set-format\": true" + } + } + +A result of 0 is returned if command succeeds along with monitored duration data, +while a result of 1 is returned if command is invalid or command processing +encounters an error. + +The format of the monitored duration data returned is determined by the +optional argument, ``result-set-format``. When false, (the default), the list +of durations will be returned as a list of individual elements as shown below: + +:: + + { + "arguments": { + "durations\": [{ + "duration-key": { + "query-type": "DHCPDISCOVER", + "response-type": "DHCPOFFER", + "start-event": "buffer_read", + "stop-event": "mt_queued", + "subnet-id": 0 + }, + "max-duration-usecs": 118, + "min-duration-usecs": 31, + "occurrences": 501, + "start-time": "2024-06-12 17:52:06.814884", + "total-duration-usecs": 23951, + "ave-duration-usecs\": 47 + }, + .., + ]", + "result-set-format": false, + "interval-width-secs": 5, + "timestamp": "2024-06-12 17:52:22.397233" + }, + "result": 0, + "text": "perfmon-get-all-durations: n found" + } + +When ``result-set-format`` is true, the list of durations will be returned in +a format similar to an SQL result set as follows: + +:: + + { + "arguments": { + "durations-result-set": { + "columns": [ + "query-type", + "response-type", + "start-event", + "end-event", + "subnet-id", + "interval-start", + "occurences", + "min-duration-usecs", + "max-duration-usecs", + "total-duration-usecsave-duration-usecs" + ], + "rows": [ [ + "DHCPDISCOVER", + "DHCPOFFER", + "buffer_read", + "mt_queued", + 0, + "2024-06-12 17:52:06.814884", + 501, + 31, + 118, + 23951, + 47 + ], + .. + ] + } + "result-set-format": true, + "interval-width-secs": 5, + "timestamp": "2024-06-12 17:52:22.397233" + }, + "result": 0, + "text": "perfmon-get-all-durations: n found" + } + +The data values for each duration will be from the duration's last completed data +interval. If a duration has no such interval, ``interval-start`` will be reported +as "" and the remaining values will be zero. + .. _perfmon-configuration: + Configuration ~~~~~~~~~~~~~ diff --git a/src/hooks/dhcp/perfmon/perfmon_mgr.cc b/src/hooks/dhcp/perfmon/perfmon_mgr.cc index 352fb4c760..1ff537d145 100644 --- a/src/hooks/dhcp/perfmon/perfmon_mgr.cc +++ b/src/hooks/dhcp/perfmon/perfmon_mgr.cc @@ -287,7 +287,6 @@ PerfMonMgr::perfmonGetAllDurationsHandler(hooks::CalloutHandle& handle) { extractCommand(handle); if (cmd_args_) { SimpleParser::checkKeywords(keywords, cmd_args_); - ConstElementPtr elem = cmd_args_->get("result-set-format"); if (elem) { result_set_format = elem->boolValue(); @@ -309,6 +308,7 @@ PerfMonMgr::perfmonGetAllDurationsHandler(hooks::CalloutHandle& handle) { // Construct the result result->set("interval-width-secs", Element::create(getIntervalWidthSecs())); result->set("timestamp", Element::create(isc::util::ptimeToText(PktEvent::now()))); + result->set("result-set-format", Element::create(result_set_format)); result->set((result_set_format ? "durations-result-set" : "durations"), formatted_durations); std::ostringstream oss; diff --git a/src/share/api/api_files.mk b/src/share/api/api_files.mk index 75d016de0b..cc3fc5f555 100644 --- a/src/share/api/api_files.mk +++ b/src/share/api/api_files.mk @@ -81,6 +81,8 @@ api_files += $(top_srcdir)/src/share/api/network6-get.json api_files += $(top_srcdir)/src/share/api/network6-list.json api_files += $(top_srcdir)/src/share/api/network6-subnet-add.json api_files += $(top_srcdir)/src/share/api/network6-subnet-del.json +api_files += $(top_srcdir)/src/share/api/perfmon-control.json +api_files += $(top_srcdir)/src/share/api/perfmon-get-all-durations.json api_files += $(top_srcdir)/src/share/api/remote-class4-del.json api_files += $(top_srcdir)/src/share/api/remote-class4-get-all.json api_files += $(top_srcdir)/src/share/api/remote-class4-get.json