[#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 07c6e3d4ad92620a58c3c0293b40e909ef388189..4e363d09b4af4f9312986a1255c8bda8139bce58 100644 (file)
--- 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 494c89f4161849e6112506d08b0238d67baf305f..691961aaeae3678e636c78d6c33bf457dcb46ea6 100644 (file)
--- 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 "<none>" 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 352fb4c76023ede72540373c453e6c4f4e06c63b..1ff537d1451392ef19f30773b8e787538561e4b4 100644 (file)
--- 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 75d016de0b0173feaa259c9f663d0f1c3be005c4..cc3fc5f555eda1ab0b0ad2ee2a9af787283073cc 100644 (file)
--- 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