Extend docs by available metrics

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/<simulationName>/<participantName>/LocalEndpoint``
+     - ``STRING_LIST``
+     - Local endpoint addresses used for the connection to the peer participant.
+   * - ``Peer/<simulationName>/<participantName>/RemoteEndpoint``
+     - ``STRING_LIST``
+     - Remote endpoint addresses used for the connection to the peer participant.
+   * - ``Peer/<simulationName>/<remoteParticipant>/tx_bytes/[bytes]``
+     - ``COUNTER``
+     - Total number of transmitted bytes for the peer connection.
+   * - ``Peer/<simulationName>/<remoteParticipant>/tx_packets/[count]``
+     - ``COUNTER``
+     - Total number of transmitted packets for the peer connection.
+   * - ``Peer/<simulationName>/<remoteParticipant>/tx_bandwidth/[Bps]``
+     - ``STATISTIC``
+     - Statistics over transmitted payload sizes, labeled in bytes per second.
+   * - ``Peer/<simulationName>/<remoteParticipant>/rx_bytes/[bytes]``
+     - ``COUNTER``
+     - Total number of received bytes for the peer connection.
+   * - ``Peer/<simulationName>/<remoteParticipant>/rx_packets/[count]``
+     - ``COUNTER``
+     - Total number of received packets for the peer connection.
+   * - ``Peer/<simulationName>/<remoteParticipant>/tx_queue_size/[count]``
+     - ``STATISTIC``
+     - Statistics over the transmit queue size for the peer connection.
+   * - ``Peer/<simulationName>/<remoteParticipant>/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 <https://vector.com/sil-kit
      - Description
 
    * - CollectFromRemote
-     - Collect metrics from all connected participants. Defaults to ``true``.
+     - Collect metrics from all connected participants. Defaults to ``true``.