diff --git a/docs/configuration/experimental-configuration.rst b/docs/configuration/experimental-configuration.rst index 8a408521e..960a708af 100644 --- a/docs/configuration/experimental-configuration.rst +++ b/docs/configuration/experimental-configuration.rst @@ -83,6 +83,130 @@ They are collected and distributed to the configured sinks at the given update i * - updateInterval - The time between sending batches of metrics to the registry in seconds. +Available Metrics +~~~~~~~~~~~~~~~~~ + +Metric names use ``/`` as a hierarchy separator. +Some metrics contain runtime-specific path elements such as the simulation name or the +name of a connected peer participant. + +.. list-table:: Available Participant Metrics + :widths: 35 15 50 + :header-rows: 1 + + * - Metric name + - Kind + - Description + * - ``SilKit/System/OperatingSystem`` + - ``ATTRIBUTE`` + - Operating system reported by the participant host. + * - ``SilKit/System/Hostname`` + - ``ATTRIBUTE`` + - Host name of the participant host. + * - ``SilKit/System/PageSize`` + - ``ATTRIBUTE`` + - Memory page size reported by the participant host. + * - ``SilKit/System/ProcessorCount`` + - ``ATTRIBUTE`` + - Number of processors reported by the participant host. + * - ``SilKit/System/ProcessorArchitecture`` + - ``ATTRIBUTE`` + - Processor architecture reported by the participant host. + * - ``SilKit/System/PhysicalMemory`` + - ``ATTRIBUTE`` + - Total physical memory of the participant host. + * - ``SilKit/Process/Executable`` + - ``ATTRIBUTE`` + - Path of the running participant executable. + * - ``SilKit/Process/Username`` + - ``ATTRIBUTE`` + - User name under which the participant process runs. + * - ``SilKit/Participant/JsonConfig`` + - ``ATTRIBUTE`` + - Participant configuration serialized as JSON. + * - ``TcpAcceptors`` + - ``STRING_LIST`` + - TCP endpoints on which the participant accepts connections. + * - ``LocalAcceptors`` + - ``STRING_LIST`` + - Local domain socket endpoints on which the participant accepts connections. + * - ``Peer///LocalEndpoint`` + - ``STRING_LIST`` + - Local endpoint addresses used for the connection to the peer participant. + * - ``Peer///RemoteEndpoint`` + - ``STRING_LIST`` + - Remote endpoint addresses used for the connection to the peer participant. + * - ``Peer///tx_bytes/[bytes]`` + - ``COUNTER`` + - Total number of transmitted bytes for the peer connection. + * - ``Peer///tx_packets/[count]`` + - ``COUNTER`` + - Total number of transmitted packets for the peer connection. + * - ``Peer///tx_bandwidth/[Bps]`` + - ``STATISTIC`` + - Statistics over transmitted payload sizes, labeled in bytes per second. + * - ``Peer///rx_bytes/[bytes]`` + - ``COUNTER`` + - Total number of received bytes for the peer connection. + * - ``Peer///rx_packets/[count]`` + - ``COUNTER`` + - Total number of received packets for the peer connection. + * - ``Peer///tx_queue_size/[count]`` + - ``STATISTIC`` + - Statistics over the transmit queue size for the peer connection. + * - ``Peer///rx_bandwidth/[Bps]`` + - ``STATISTIC`` + - Statistics over received payload sizes, labeled in bytes per second. + * - ``SimStepCount`` + - ``COUNTER`` + - Number of completed simulation steps. + * - ``SimStep/execution_duration/[s]`` + - ``STATISTIC`` + - Statistics over simulation step handler execution time in seconds. + * - ``SimStep/completion_duration/[s]`` + - ``STATISTIC`` + - Statistics over asynchronous simulation step completion time in seconds. + * - ``SimStep/waiting_duration/[s]`` + - ``STATISTIC`` + - Statistics over waiting time between simulation steps in seconds. + +Metric Value Encoding +~~~~~~~~~~~~~~~~~~~~~ + +The metric kind determines the format of the metric value: + +.. list-table:: Metric Value Encoding + :widths: 15 85 + :header-rows: 1 + + * - Kind + - Value format + * - ``COUNTER`` + - A single integer value. + * - ``STATISTIC`` + - A JSON array ``[mean, stddev, min, max]``. + * - ``STRING_LIST`` + - A JSON array of strings. + * - ``ATTRIBUTE`` + - A string value. + +Example JSON Output +~~~~~~~~~~~~~~~~~~~ + +The ``JsonFile`` sink writes one JSON object per line. +Each object contains the timestamp in nanoseconds (``ts``), the participant name (``pn``), +the metric name (``mn``), the metric kind (``mk``), and the metric value (``mv``). + +.. code-block:: json + + {"ts":1716200000000000000,"pn":"Participant1","mn":"SimStepCount","mk":"COUNTER","mv":42} + {"ts":1716200000000100000,"pn":"Participant1","mn":"SimStep/execution_duration/[s]","mk":"STATISTIC","mv":[0.0017,0.0004,0.0012,0.0025]} + {"ts":1716200000000200000,"pn":"Participant1","mn":"Peer/Sim1/Participant2/tx_bytes/[bytes]","mk":"COUNTER","mv":32768} + {"ts":1716200000000300000,"pn":"Participant1","mn":"Peer/Sim1/Participant2/RemoteEndpoint","mk":"STRING_LIST","mv":["tcp://10.0.0.2:8500"]} + +The exact set of emitted metrics depends on which SIL Kit services are used and which peer +connections are established during the simulation run. + .. _sec:cfg-registry-experimental: Metrics for the registry @@ -108,4 +232,4 @@ Refer to the documentation of the `SIL Kit Dashboard