[#3328] Addressed review comments

Revampe UTs
Replaced ave and average with mean throughout

Author: tmarkwalder

doc/sphinx/arm/hooks-perfmon.rst

@@ -170,29 +170,29 @@ statistic employs the following naming convention:
     {subnet-id[x]}.perfmon.<query type>-<response type>.<start event>-<end event>.<value-name>
 
 There is both a global and a subnet-specific value for each. Currently, the only
-value reported for a given duration key is ``averages-usecs``; this statistic is the average time
+value reported for a given duration key is ``mean-usecs``; this statistic is the mean time
 between the duration's event pair over the most recently completed interval. In other
 words, if during a given interval there were seven occurrences (i.e. updates) totaling
-3500us, the ``average-usecs`` reported would be 500us. Continuing with the example above, the
+3500us, the ``mean-usecs`` reported would be 500us. Continuing with the example above, the
 statistics reported are named as follows for the subnet-level values:
 
 ::
 
-    subnet[100].perfmon.DHCPDISCOVER.DHCPOFFER.socket_received-buffer_read.average-usecs
-    subnet[100].perfmon.DHCPDISCOVER.DHCPOFFER.buffer_read-mt_queue.average-usecs
-    subnet[100].perfmon.DHCPDISCOVER.DHCPOFFER.mt_queued-process_started.average-usecs
-    subnet[100].perfmon.DHCPDISCOVER.DHCPOFFER.process_started-process_completed.average-usecs
-    subnet[100].perfmon.DHCPDISCOVER.DHCPOFFER.composite-total_response.average-usecs
+    subnet[100].perfmon.DHCPDISCOVER.DHCPOFFER.socket_received-buffer_read.mean-usecs
+    subnet[100].perfmon.DHCPDISCOVER.DHCPOFFER.buffer_read-mt_queue.mean-usecs
+    subnet[100].perfmon.DHCPDISCOVER.DHCPOFFER.mt_queued-process_started.mean-usecs
+    subnet[100].perfmon.DHCPDISCOVER.DHCPOFFER.process_started-process_completed.mean-usecs
+    subnet[100].perfmon.DHCPDISCOVER.DHCPOFFER.composite-total_response.mean-usecs
 
 and as shown for global values:
 
 ::
 
-    perfmon.DHCPDISCOVER.DHCPOFFER.socket_received-buffer_read.average-usecs
-    perfmon.DHCPDISCOVER.DHCPOFFER.buffer_read-mt_queue.average-usecs
-    perfmon.DHCPDISCOVER.DHCPOFFER.mt_queued-process_started.average-usecs
-    perfmon.DHCPDISCOVER.DHCPOFFER.process_started-process_completed.average-usecs
-    perfmon.DHCPDISCOVER.DHCPOFFER.composite-total_response.average-usecs
+    perfmon.DHCPDISCOVER.DHCPOFFER.socket_received-buffer_read.mean-usecs
+    perfmon.DHCPDISCOVER.DHCPOFFER.buffer_read-mt_queue.mean-usecs
+    perfmon.DHCPDISCOVER.DHCPOFFER.mt_queued-process_started.mean-usecs
+    perfmon.DHCPDISCOVER.DHCPOFFER.process_started-process_completed.mean-usecs
+    perfmon.DHCPDISCOVER.DHCPOFFER.composite-total_response.mean-usecs
 
 The results are reported to StatsMgr, an internal Kea component that reports data as statistics
 that can be retrieved using statistics commands. They can be fetched using the commands
@@ -202,25 +202,25 @@ Alarms
 ~~~~~~
 
 Alarms may be defined to watch specific durations. Each alarm defines a high-water mark,
-``high-water-ms``, and a low-water mark, ``low-water-ms``. If the reported average value
+``high-water-ms``, and a low-water mark, ``low-water-ms``. If the reported mean value
 for the duration exceeds the high-water mark a WARN level alarm log is emitted, at which
 point the alarm is considered "triggered." Once triggered, the WARN level log is
 repeated at the alarm report interval specified by ``alarm-report-secs``, as long as the reported
-average for the duration remains above the low-water mark. Once the average falls below the
+mean for the duration remains above the low-water mark. Once the mean falls below the
 low-water mark the alarm is cleared and an INFO level log is emitted.
 
 The alarm-triggered WARN log looks similar to the following:
 
 ::
 
-    2024-03-20 10:22:14.030 WARN [kea-dhcp6.leases/47195.139913679886272] PERFMON_ALARM_TRIGGERED Alarm for DHCPDISCOVER.DHCPOFFER.composite-total_response.0 has been triggered since 2024-03-20 10:18:20.070000, reported average duration 00:00:00.700000 exceeds high-water-ms: 500
+    2024-03-20 10:22:14.030 WARN [kea-dhcp6.leases/47195.139913679886272] PERFMON_ALARM_TRIGGERED Alarm for DHCPDISCOVER.DHCPOFFER.composite-total_response.0 has been triggered since 2024-03-20 10:18:20.070000, reported mean duration 00:00:00.700000 exceeds high-water-ms: 500
 
 
 The alarm-cleared INFO log looks like this:
 
 ::
 
-     2024-03-20 10:30:14.030 INFO [kea-dhcp6.leases/47195.139913679886272] PERFMON_ALARM_CLEARED Alarm for DHCPDISCOVER.DHCPOFFER.composite-total_response.0 has been cleared, reported average duration 00:00:00.010000 is now below low-water-ms: 25
+     2024-03-20 10:30:14.030 INFO [kea-dhcp6.leases/47195.139913679886272] PERFMON_ALARM_CLEARED Alarm for DHCPDISCOVER.DHCPOFFER.composite-total_response.0 has been cleared, reported mean duration 00:00:00.010000 is now below low-water-ms: 25
 
 API Commands
 ~~~~~~~~~~~~
@@ -301,7 +301,7 @@ of durations will be returned as a list of individual elements as shown below:
                "occurrences": 501,
                "start-time": "2024-06-12 17:52:06.814884",
                "total-duration-usecs": 23951,
-               "ave-duration-usecs": 47
+               "mean-duration-usecs": 47
             },
             ...
            ],
@@ -328,10 +328,11 @@ a format similar to an SQL result set as follows:
                     "end-event",
                     "subnet-id",
                     "interval-start",
-                    "occurences",
+                    "occurrence",
                     "min-duration-usecs",
                     "max-duration-usecs",
-                    "total-duration-usecsave-duration-usecs"
+                    "total-duration-usecs",
+                    "mean-duration-usecs"
                 ],
                 "rows": [ [
                     "DHCPDISCOVER",

src/hooks/dhcp/perfmon/alarm.h

@@ -34,8 +34,8 @@ class Alarm : public DurationKey {
     /// @param start_event_label label of the start event
     /// @param stop_event_label label of the end event
     /// @param subnet_id SubnetID of the selected subnet
-    /// @param low_water threshold below which the average duration must fall to clear the alarm
-    /// @param high_water threshold above which the average duration must rise to trigger the alarm
+    /// @param low_water threshold below which the mean duration must fall to clear the alarm
+    /// @param high_water threshold above which the mean duration must rise to trigger the alarm
     /// @param enabled true sets state to CLEAR, otherwise DISABLED, defaults to true
     Alarm(uint16_t family, uint8_t query_type, uint8_t response_type,
           const std::string& start_event_label, const std::string& stop_event_label,
@@ -45,8 +45,8 @@ class Alarm : public DurationKey {
     /// @brief Constructor
     ///
     /// @param key composite key that identifies the alarm
-    /// @param low_water threshold below which the average duration must fall to clear the alarm
-    /// @param high_water threshold above which the average duration must rise to trigger the alarm
+    /// @param low_water threshold below which the mean duration must fall to clear the alarm
+    /// @param high_water threshold above which the mean duration must rise to trigger the alarm
     /// @param enabled true sets state to CLEAR, otherwise DISABLED, defaults to true
     Alarm(const DurationKey& key, const Duration& low_water, const Duration& high_water, bool enabled = true);
 
@@ -148,10 +148,10 @@ class Alarm : public DurationKey {
     bool checkSample(const Duration& sample, const Duration& report_interval);
 
 private:
-    /// @brief Threshold below which the average duration must fall to clear the alarm.
+    /// @brief Threshold below which the mean duration must fall to clear the alarm.
     Duration low_water_;
 
-    /// @brief Threshold above which the average duration must rise to trigger the alarm.
+    /// @brief Threshold above which the mean duration must rise to trigger the alarm.
     Duration high_water_;
 
     /// @brief Current alarm state.

src/hooks/dhcp/perfmon/alarm_store.h

@@ -105,8 +105,8 @@ class AlarmStore {
     /// @brief Creates a new alarm and adds it to the store
     ///
     /// @param key key value of the alarm to create.
-    /// @param low_water threshold below which the average duration must fall to clear the alarm
-    /// @param high_water threshold above which the average duration must rise to trigger the alarm.
+    /// @param low_water threshold below which the mean duration must fall to clear the alarm
+    /// @param high_water threshold above which the mean duration must rise to trigger the alarm.
     /// @param enabled true sets state to CLEAR, otherwise DISABLED, defaults to true.
     ///
     /// @return pointer to the newly created alarm.

src/hooks/dhcp/perfmon/monitored_duration.cc

@@ -44,7 +44,7 @@ DurationDataInterval::addDuration(const Duration& duration) {
 }
 
 Duration
-DurationDataInterval::getAverageDuration() const {
+DurationDataInterval::getMeanDuration() const {
     if (!occurrences_) {
         return (ZERO_DURATION());
     }
@@ -333,14 +333,14 @@ MonitoredDuration::toElement() const {
         element->set("min-duration-usecs", Element::create(previous_interval_->getMinDuration().total_microseconds()));
         element->set("max-duration-usecs", Element::create(previous_interval_->getMaxDuration().total_microseconds()));
         element->set("total-duration-usecs", Element::create(previous_interval_->getTotalDuration().total_microseconds()));
-        element->set("ave-duration-usecs", Element::create(previous_interval_->getAverageDuration().total_microseconds()));
+        element->set("mean-duration-usecs", Element::create(previous_interval_->getMeanDuration().total_microseconds()));
     } else {
         element->set("start-time", Element::create("<none>"));
         element->set("occurrences", Element::create(0));
         element->set("min-duration-usecs", Element::create(0));
         element->set("max-duration-usecs", Element::create(0));
         element->set("total-duration-usecs", Element::create(0));
-        element->set("ave-duration-usecs", Element::create(0));
+        element->set("mean-duration-usecs", Element::create(0));
     }
 
     return (element);
@@ -359,7 +359,7 @@ MonitoredDuration::valueRowColumns() {
         "min-duration-usecs",
         "max-duration-usecs",
         "total-duration-usecs"
-        "ave-duration-usecs"
+        "mean-duration-usecs"
     };
 
     static ElementPtr cols;
@@ -393,7 +393,7 @@ MonitoredDuration::toValueRow() const {
         row->add(Element::create(previous_interval_->getMinDuration().total_microseconds()));
         row->add(Element::create(previous_interval_->getMaxDuration().total_microseconds()));
         row->add(Element::create(previous_interval_->getTotalDuration().total_microseconds()));
-        row->add(Element::create(previous_interval_->getAverageDuration().total_microseconds()));
+        row->add(Element::create(previous_interval_->getMeanDuration().total_microseconds()));
     } else {
         row->add(Element::create("<none>"));
         row->add(Element::create(0));

src/hooks/dhcp/perfmon/monitored_duration.h

@@ -8,6 +8,7 @@
 #define _MONITORED_DURATION_H
 
 #include <cc/data.h>
+#include <cc/cfg_to_element.h>
 #include <dhcp/pkt.h>
 #include <dhcpsrv/subnet_id.h>
 
@@ -90,10 +91,10 @@ class DurationDataInterval {
         return (total_duration_);
     }
 
-    /// @brief Get the average duration for the interval.
+    /// @brief Get the mean duration for the interval.
     ///
-    /// @return Duration containing the average.
-    Duration getAverageDuration() const;
+    /// @return Duration containing the mean.
+    Duration getMeanDuration() const;
 
     /// @brief Equality operator.
     ///
@@ -130,7 +131,7 @@ typedef boost::shared_ptr<DurationDataInterval> DurationDataIntervalPtr;
 /// -# Start Event
 /// -# Stop Event
 /// -# Subnet ID can be GLOBAL_SUBNET_ID for aggregate durations
-class DurationKey {
+class DurationKey : public data::CfgToElement {
 public:
     /// @brief Constructor
     ///
@@ -227,7 +228,7 @@ class DurationKey {
 
     /// @brief Get the StatsMgr formatted compatible name.
     ///
-    /// @param value_name name of the specific value (e.g. "average-usecs", "min-duration-usecs").
+    /// @param value_name name of the specific value (e.g. "mean-usecs", "min-duration-usecs").
     /// The format of the string:
     ///
     /// @code
@@ -236,9 +237,9 @@ class DurationKey {
     ///
     /// Examples:
     ///
-    ///  perfmon.discover-offer.socket_received-buffer_read.average-usecs
+    ///  perfmon.discover-offer.socket_received-buffer_read.mean-usecs
     ///
-    ///  subnet[9].perfmon.discover-offer.socket_received-buffer_read.average-usecs
+    ///  subnet[9].perfmon.discover-offer.socket_received-buffer_read.mean-usecs
     ///
     /// @endcode
     ///
@@ -415,8 +416,8 @@ class MonitoredDuration : public DurationKey {
     ///      "min-duration-usecs": 5300,
     ///      "max-duration-usecs": 9000,
     ///      "total-duration-usecs": 786500,
-    ///      "ave-duration-usecs": 7490
-    ///      }
+    ///      "mean-duration-usecs": 7490
+    /// }
     /// @endcode
     ///
     /// If there is no previous interval, it will appears as follows:
@@ -435,8 +436,8 @@ class MonitoredDuration : public DurationKey {
     ///      "min-duration-usecs": 0,
     ///      "max-duration-usecs": 0,
     ///      "total-duration-usecs": 0,
-    ///      "ave-duration-usecs": 0
-    ///      }
+    ///      "mean-duration-usecs": 0
+    /// }
     /// @endcode
     ///
     /// @return Element::map containing the duration key values.
@@ -459,7 +460,7 @@ class MonitoredDuration : public DurationKey {
     /// -# "min-duration-usecs"
     /// -# "max-duration-usecs"
     /// -# "total-duration-usecs"
-    /// -# "ave-duration-usecs"
+    /// -# "mean-duration-usecs"
     ///
     /// @return Element::map containing the duration key values.
     static data::ConstElementPtr valueRowColumns();
@@ -483,7 +484,7 @@ class MonitoredDuration : public DurationKey {
     /// -# min-duration-usecs      Element::int
     /// -# max-duration-usecs      Element::int
     /// -# total-duration-usecs    Element::int
-    /// -# ave-duration-usecs      Element::int
+    /// -# mean-duration-usecs     Element::int
     ///
     /// @return Element::map containing the duration key values.
     data::ElementPtr toValueRow() const;

src/hooks/dhcp/perfmon/perfmon_messages.cc

@@ -24,8 +24,8 @@ extern const isc::log::MessageID PERFMON_INIT_OK = "PERFMON_INIT_OK";
 namespace {
 
 const char* values[] = {
-    "PERFMON_ALARM_CLEARED", "Alarm for %1 has been cleared, reported average duration %2 is now below low-water-ms: %3",
-    "PERFMON_ALARM_TRIGGERED", "Alarm for %1 has been triggered since %2, reported average duration %3 exceeds high-water-ms: %4",
+    "PERFMON_ALARM_CLEARED", "Alarm for %1 has been cleared, reported mean duration %2 is now below low-water-ms: %3",
+    "PERFMON_ALARM_TRIGGERED", "Alarm for %1 has been triggered since %2, reported mean duration %3 exceeds high-water-ms: %4",
     "PERFMON_CMDS_CONTROL_ERROR", "perfmon-control command processing failed: %1",
     "PERFMON_CMDS_CONTROL_OK", "perfmon-control command success: active monitoring: %1, stats-mgr-reporting: %2",
     "PERFMON_CMDS_GET_ALL_DURATIONS_ERROR", "perfmon-get-all-durations command processing failed: %1",

src/hooks/dhcp/perfmon/perfmon_messages.mes

@@ -1,18 +1,18 @@
 # Copyright (C) 2024 Internet Systems Consortium, Inc. ("ISC")
 
-% PERFMON_ALARM_CLEARED Alarm for %1 has been cleared, reported average duration %2 is now below low-water-ms: %3
-This info message is emitted when the reported average duration for
+% PERFMON_ALARM_CLEARED Alarm for %1 has been cleared, reported mean duration %2 is now below low-water-ms: %3
+This info message is emitted when the reported mean duration for
 an alarm that has been triggered has fallen below the value of its
 low-water-ms parameter. The arguments detail the alarm's key and
-the most recently reported average.
+the most recently reported mean.
 
-% PERFMON_ALARM_TRIGGERED Alarm for %1 has been triggered since %2, reported average duration %3 exceeds high-water-ms: %4
-This warning message is emitted when the reported average duration for
+% PERFMON_ALARM_TRIGGERED Alarm for %1 has been triggered since %2, reported mean duration %3 exceeds high-water-ms: %4
+This warning message is emitted when the reported mean duration for
 an alarm exceeds its high-water-ms value.  As long as the reported
 averges remain above the low-water-ms value, the alarm will remain
 triggered and this message will be repeated every alarm-report-secs.
 Arguments detail the alarm's key, the time the alarm was first
-triggered, the most recent reported average, and the high-water-ms
+triggered, the most recent reported mean, and the high-water-ms
 value.
 
 % PERFMON_DEINIT_FAILED unloading PerfMon hooks library failed: %1