feat: ✨ add ecos get_appliance_realtime_stats function for direct realtime stats from appliance

update docstring in Orchestrator get_realtime_stats function to correspond to appliance equivalent function

Author: zachcamara-hpe

pyedgeconnect/__init__.py

@@ -1420,6 +1420,7 @@ def __init__(
     )
     from .ecos._sp_portal import register_sp_portal, register_sp_portal_status
     from .ecos._statistics import (
+        get_appliance_realtime_stats,
         get_appliance_stats_minute_file,
         get_appliance_stats_minute_range,
     )

pyedgeconnect/ecos/_statistics.py

@@ -84,3 +84,117 @@ def get_appliance_stats_minute_file(
         f"/stats/minuteStats/{file}",
         return_type="full_response",
     )
+
+
+def get_appliance_realtime_stats(
+    self,
+    stat_type: str,
+    stat_name: str,
+    stat_filter: str = "",
+) -> dict:
+    """Get real time per second statistics. This endpoint returns
+    varying responses based on the parameters specified in the body.
+
+    .. list-table::
+        :header-rows: 1
+
+        * - Swagger Section
+          - Method
+          - Endpoint
+        * - statistics
+          - POST
+          - /stats/realtimeStats
+
+    .. note::
+
+        Appliances store per second statistics for only 3 seconds. You
+        must poll at a frequency faster than 3 seconds to not have gaps
+        in the results when trying to collect continious values.
+
+
+    * For **Tunnel stats**: Set ``stat_type`` to ``tunnel`` and set
+      ``stat_name`` to one of the tunnel names or ``pass-through`` or
+      ``pass-through-unshaped``. ``stat_filter`` is not used for tunnel
+      statistics.
+
+    * For **TrafficType stats**: Set the ``stat_type`` to
+      ``trafficType`` to retrieve two aggregate real-time stats:
+      optimized and all-traffic. For optimized, set ``stat_name`` to
+      ``0`` and for all-traffic, set ``stat_name`` to ``3``.
+      ``stat_filter`` is not used.
+
+    * For **Application stats**: Set ``stat_type`` to ``app``. Set
+      ``stat_name`` to application name. ``stat_filter`` is required.
+      Accepted values are ``0`` for optimized traffic, ``1`` for
+      passthrough shaped, ``2`` for passthrough unshaped, and ``3`` for
+      all traffic.
+
+    * For **DSCP stats**: Set ``stat_type`` to ``dscp``, set
+      ``stat_name`` to one of DSCP values from ``0`` to ``63``.
+      ``stat_filter`` is required. Accepted values are ``0`` for
+      optimized traffic, ``1`` for passthrough shaped, ``2`` for
+      passthrough unshaped, and ``3`` for all traffic.
+
+    * For **Traffic Class Stats**: set ``stat_type`` to 'trafficClass',
+      set ``stat_name`` to one of traffic classes from ``0`` to ``9``.
+      ``stat_filter`` is required. Accepted values are ``0`` for
+      optimized traffic, ``1`` for passthrough shaped, ``2`` for
+      passthrough unshaped, and ``3`` for all traffic.
+
+    * For **Flow stats**: set type to ``flow``, name to ``0`` for TCP
+      accelerated, ``1`` for TCP unaccelerated and ``2`` for non-TCP
+      flows. ``3`` for all traffic. ``stat_filter`` is required.
+      Accepted values are ``0`` for optimized traffic, ``1`` for
+      passthrough shaped, ``2`` for passthrough unshaped, and ``3``
+      for all traffic.
+
+    * For **Shaper stats**: Set ``stat_type`` to ``shaper``. Set
+      ``stat_name`` to one of traffic classes from ``0`` to ``9``.
+      ``stat_filter`` to traffic direction, ``0`` for Outbound and ``1``
+      for Inbound.
+
+    * For **Drops stats**: Set ``stat_type`` to ``drops``. Set
+      ``stat_name`` to empty string
+
+    * For **Interface stats**: set type to ``interface``, and
+      ``stat_name`` to interface name. Use ``stat_filter`` to filter
+      traffic type, ``0`` for optimized traffic, ``1`` for
+      passthrough shaped, ``2`` for passthrough unshaped, and ``3``
+      for all traffic.
+
+    :param stat_type: Category/Type of statistics to retrieve, accepted
+      values included ``tunnel``, ``trafficType``, ``app``, ``flow``,
+      ``dscp``, ``trafficClass``, ``shaper``, ``drops``, and
+      ``interface``
+    :type stat_type: str
+    :param stat_name: Name of value to retrieve, accepted values
+      dependent on value of param ``stat_type``
+    :type stat_name: str
+    :param stat_filter: Required for certain stat types, accepted values
+      are ``0``, ``1``, ``2``, ``3``, function of which is dependent
+      on value of ``stat_type`` and ``stat_name``, defaults to ""
+    :type stat_filter: str, optional
+    :return: Dictionary of realtime stats for specified parameters \n
+        * keyword **<name_of_stat>** (`list`): 3 second stat object,
+          number of keys varies based on stat type queried \n
+          * [`list`]: First second list of stat timestamp and value \n
+            * [0] (`int`): Epoch timestamp in microseconds
+            * [1] (`int`): Stat value, unit dependent on stat type
+          * [`list`]: Second second list of stat timestamp and value \n
+            * [0] (`int`): Epoch timestamp in microseconds
+            * [1] (`int`): Stat value, unit dependent on stat type
+          * [`list`]: Third second list of stat timestamp and value \n
+            * [0] (`int`): Epoch timestamp in microseconds
+            * [1] (`int`): Stat value, unit dependent on stat type
+    :rtype: dict
+    """
+    data = {
+        "type": stat_type,
+        "name": stat_name,
+        "filter": stat_filter,
+    }
+
+    return self._post(
+        "/stats/realtimeStats",
+        data=data,
+    )

pyedgeconnect/orch/_realtime_stats.py

@@ -9,7 +9,7 @@ def get_realtime_stats(
     ne_pk: str,
     stat_type: str,
     stat_name: str,
-    stat_filter: str,
+    stat_filter: str = "",
 ) -> dict:
     """Get real time statistics from appliance based on query parameters
 
@@ -23,65 +23,90 @@ def get_realtime_stats(
           - POST
           - /realtimeStats/{nePk}
 
-    * Tunnel stats: Set ``stat_type`` to ``tunnel``. Set ``stat_name``
-      to one of the tunnel names or ``pass-through`` or
-      ``pass-through-unshaped``. ``stat_filter`` is not used for
-      tunnel statistics.
-    * TrafficType stats: Set the ``stat_type`` to ``trafficType`` to
-      retrieve two aggregate real-time stats: optimized, all-traffic.
-      For optimized, set ``stat_name`` to ``0`` and for all-traffic,
-      set ``stat_name`` to ``3``. ``stat_filter`` is not used.
-    * Application stats: Set ``stat_type`` to ``app``. Set ``stat_name``
-      to application name. ``stat_filter`` is required.
-    * DSCP stats: Set ``stat_type`` to ``dscp``, set name to one of DSCP
-      values from ``0`` to ``63``. ``stat_filter`` is required.
-      Possible ``stat_filter`` values are ``0`` for optimized_traffic,
-      ``1`` for pass_through_shaped, ``2`` for pass_through_unshaped,
-      and ``3`` for all_traffic
-    * MOS stats: Set ``stat_name`` to a tunnel id and set ``stat_type``
-      to ``tunnel``
-    * Traffic Class Stats: set ``stat_type`` to ``trafficClass``, set
-      ``stat_name`` to one of traffic classes from ``0`` to ``9``.
-      ``stat_filter`` is required.
-    * Flow stats: set ``stat_type`` to ``flow``, ``stat_name`` to ``0``
-      for TCP accelerated, ``1`` for TCP unaccelerated, and ``2`` for
-      non-TCP flows. ``stat_filter`` is required. Accepted values for
-      ``stat_filter`` values are ``0`` for optimized_traffic, ``1`` for
-      pass_through_shaped, ``2`` for pass_through_unshaped, and ``3``
-      for all_traffic
-    * Shaper stats: Set ``stat_type`` to ``shaper``. Set ``stat_name``
-      to one of traffic classes from ``0`` to ``9``. Use ``stat_filter``
-      to specify traffic direction:  ``0`` for Outbound and ``1`` for
-      Inbound)
-    * Drops stats: Set ``stat_type`` to ``drops``. Set ``stat_name`` to
-      empty string.
-    * Interface stats: Set ``stat_type`` to ``interface``. Set
-      ``stat_name`` to interface name. Use ``stat_filter`` to filter
-      traffic type: ``0`` for optimized_traffic, ``1`` for
-      pass_through_shaped, ``2`` for pass_through_unshaped, and ``3``
-      for all_traffic
 
     .. note::
-      Appliances store per second statistics for three seconds. You must
-      poll at a frequency faster than three seconds to make sure to not
-      have gaps in the results. The result format for all statistics
-      looks like: ``{'nameofstat': [time, value], [time,value],...}``
-      where you get statistics for last three seconds.
+
+        Appliances store per second statistics for only 3 seconds. You
+        must poll at a frequency faster than 3 seconds to not have gaps
+        in the results when trying to collect continious values.
+
+
+    * For **Tunnel stats**: Set ``stat_type`` to ``tunnel`` and set
+      ``stat_name`` to one of the tunnel names or ``pass-through`` or
+      ``pass-through-unshaped``. ``stat_filter`` is not used for tunnel
+      statistics.
+
+    * For **TrafficType stats**: Set the ``stat_type`` to
+      ``trafficType`` to retrieve two aggregate real-time stats:
+      optimized and all-traffic. For optimized, set ``stat_name`` to
+      ``0`` and for all-traffic, set ``stat_name`` to ``3``.
+      ``stat_filter`` is not used.
+
+    * For **Application stats**: Set ``stat_type`` to ``app``. Set
+      ``stat_name`` to application name. ``stat_filter`` is required.
+      Accepted values are ``0`` for optimized traffic, ``1`` for
+      passthrough shaped, ``2`` for passthrough unshaped, and ``3`` for
+      all traffic.
+
+    * For **DSCP stats**: Set ``stat_type`` to ``dscp``, set
+      ``stat_name`` to one of DSCP values from ``0`` to ``63``.
+      ``stat_filter`` is required. Accepted values are ``0`` for
+      optimized traffic, ``1`` for passthrough shaped, ``2`` for
+      passthrough unshaped, and ``3`` for all traffic.
+
+    * For **Traffic Class Stats**: set ``stat_type`` to 'trafficClass',
+      set ``stat_name`` to one of traffic classes from ``0`` to ``9``.
+      ``stat_filter`` is required. Accepted values are ``0`` for
+      optimized traffic, ``1`` for passthrough shaped, ``2`` for
+      passthrough unshaped, and ``3`` for all traffic.
+
+    * For **Flow stats**: set type to ``flow``, name to ``0`` for TCP
+      accelerated, ``1`` for TCP unaccelerated and ``2`` for non-TCP
+      flows. ``3`` for all traffic. ``stat_filter`` is required.
+      Accepted values are ``0`` for optimized traffic, ``1`` for
+      passthrough shaped, ``2`` for passthrough unshaped, and ``3``
+      for all traffic.
+
+    * For **Shaper stats**: Set ``stat_type`` to ``shaper``. Set
+      ``stat_name`` to one of traffic classes from ``0`` to ``9``.
+      ``stat_filter`` to traffic direction, ``0`` for Outbound and ``1``
+      for Inbound.
+
+    * For **Drops stats**: Set ``stat_type`` to ``drops``. Set
+      ``stat_name`` to empty string
+
+    * For **Interface stats**: set type to ``interface``, and
+      ``stat_name`` to interface name. Use ``stat_filter`` to filter
+      traffic type, ``0`` for optimized traffic, ``1`` for
+      passthrough shaped, ``2`` for passthrough unshaped, and ``3``
+      for all traffic.
 
     :param ne_pk: Network Primary Key (nePk) of appliance, e.g. ``3.NE``
     :type ne_pk: str
-    :param stat_type: Type of statistic to retreive, accepted values
-        include ``tunnel``, ``trafficType``, ``app``, ``flow``,
-        ``dscp``, ``trafficClass``, ``shaper``, and ``drops``
+    :param stat_type: Category/Type of statistics to retrieve, accepted
+      values included ``tunnel``, ``trafficType``, ``app``, ``flow``,
+      ``dscp``, ``trafficClass``, ``shaper``, ``drops``, and
+      ``interface``
     :type stat_type: str
     :param stat_name: Name of value to retrieve, accepted values
-        dependent on value of param ``type``
+      dependent on value of param ``stat_type``
     :type stat_name: str
-    :param stat_filter: Filter results, accepted values are ``0``,
-        ``1``, ``2``, ``3``, functions dependent on value of param
-        ``type`` and ``name``
-    :type stat_filter: str
-    :return: Returns nested dictionary
+    :param stat_filter: Required for certain stat types, accepted values
+      are ``0``, ``1``, ``2``, ``3``, function of which is dependent
+      on value of ``stat_type`` and ``stat_name``, defaults to ""
+    :type stat_filter: str, optional
+    :return: Dictionary of realtime stats for specified parameters \n
+        * keyword **<name_of_stat>** (`list`): 3 second stat object,
+          number of keys varies based on stat type queried \n
+          * [`list`]: First second list of stat timestamp and value \n
+            * [0] (`int`): Epoch timestamp in microseconds
+            * [1] (`int`): Stat value, unit dependent on stat type
+          * [`list`]: Second second list of stat timestamp and value \n
+            * [0] (`int`): Epoch timestamp in microseconds
+            * [1] (`int`): Stat value, unit dependent on stat type
+          * [`list`]: Third second list of stat timestamp and value \n
+            * [0] (`int`): Epoch timestamp in microseconds
+            * [1] (`int`): Stat value, unit dependent on stat type
     :rtype: dict
     """
     data = {"type": stat_type, "name": stat_name, "filter": stat_filter}