.. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2026 Intel Corporation dpdk-telemetry-watcher Tool =========================== The ``dpdk-telemetry-watcher`` tool monitors DPDK telemetry statistics continuously on the command line. It wraps the ``dpdk-telemetry.py`` script to provide real-time statistics display capabilities. Running the Tool ---------------- The watcher tool can be run at any time, whether or not a DPDK application is currently running. When a DPDK application with telemetry enabled starts (assuming correct file-prefix and instance are specified), the watcher will automatically connect and begin displaying the requested statistics. If the DPDK application stops, the watcher will attempt to reconnect when the application restarts. The tool has a number of command line options: .. code-block:: console dpdk-telemetry-watcher.py [options] stat1 stat2 ... Options ------- .. program:: dpdk-telemetry-watcher.py .. option:: -h, --help Display usage information and quit .. option:: -f FILE_PREFIX, --file-prefix FILE_PREFIX Provide file-prefix for DPDK runtime directory. Passed to ``dpdk-telemetry.py`` to identify the target DPDK application. Default is ``rte``. .. option:: -i INSTANCE, --instance INSTANCE Provide instance number for DPDK application when multiple applications share the same file-prefix. Passed to ``dpdk-telemetry.py`` to identify the target DPDK application instance. Default is ``0``. .. option:: -l, --list List all possible file-prefixes and exit. This is useful to discover which DPDK applications are currently running. .. option:: -t TIMEOUT, --timeout TIMEOUT Number of iterations to run before exiting. If not specified, the tool runs indefinitely until interrupted with Ctrl+C. .. option:: -d, --delta Display delta values instead of absolute values. This shows the change in statistics since the last iteration, which is useful for monitoring per-second rates. .. option:: -T, --total Display a total column at the end of each row that sums all monitored statistics. .. option:: -1, --single-line Display output on a single line, replacing the previous output. This is useful for reducing scrolling and keeping the display compact. .. option:: stat Statistics to monitor in format ``command.field``. Multiple statistics can be specified and will be displayed in columns. See the `Statistics Format`_ section below for details on specifying statistics. Statistics Format ----------------- Specify statistics in the format ``command.field`` where: * ``command`` is a telemetry command (e.g., ``/ethdev/stats,0``) * ``field`` is a field name from the command's JSON response (e.g., ``ipackets``) To discover available commands and fields, follow the steps below: 1. Use ``dpdk-telemetry.py`` interactively to explore available commands 2. Use the ``/`` command to list all available telemetry endpoints 3. Query specific commands to see their response format Example telemetry commands: * ``/ethdev/list`` - List all Ethernet devices * ``/ethdev/stats,N`` - Get statistics for Ethernet device N * ``/ethdev/xstats,N`` - Get extended statistics for Ethernet device N * ``/eal/mempool_list`` - List all mempools * ``/mempool/info,N`` - Get information about mempool N See `Examples`_ section for usage examples based on the results of these telemetry commands. Shortcuts --------- The tool provides convenient shortcuts for common statistics: * ``eth.rx`` - Expands to ``/ethdev/stats,N.ipackets`` for all Ethernet devices * ``eth.tx`` - Expands to ``/ethdev/stats,N.opackets`` for all Ethernet devices * ``eth.FIELD`` - Expands to ``/ethdev/stats,N.FIELD`` for all Ethernet devices These shortcuts automatically detect all available Ethernet devices and create a column for each one. Examples -------- Monitor received packets on Ethernet device 0:: dpdk-telemetry-watcher.py /ethdev/stats,0.ipackets Monitor received and transmitted packets on device 0:: dpdk-telemetry-watcher.py /ethdev/stats,0.ipackets /ethdev/stats,0.opackets Monitor received packets on all Ethernet devices using shortcut:: dpdk-telemetry-watcher.py eth.rx Monitor packet deltas (rates) for device 0:: dpdk-telemetry-watcher.py -d /ethdev/stats,0.ipackets /ethdev/stats,0.opackets Monitor with a total column showing aggregate traffic:: dpdk-telemetry-watcher.py -d -T eth.rx eth.tx Monitor for a specific duration (60 iterations = 60 seconds):: dpdk-telemetry-watcher.py -t 60 /ethdev/stats,0.ipackets Monitor a DPDK application with a custom file-prefix:: dpdk-telemetry-watcher.py -f myapp /ethdev/stats,0.ipackets Monitor in single-line mode (no scrolling):: dpdk-telemetry-watcher.py -1 -d eth.rx eth.tx List all running DPDK applications:: dpdk-telemetry-watcher.py -l Output Format ------------- The tool displays statistics in a tabular format with: * **Time column** - Current timestamp (HH:MM:SS) * **Statistics columns** - One column per specified statistic * **Total column** - Optional sum of all statistics (when ``-T`` is used) Displayed values use locale-specific number formatting (e.g. comma as thousands separator). When ``--delta`` mode is enabled, the tool displays the change in each statistic since the last iteration, which typically represents the rate per second. When ``--single-line`` mode is enabled, each new output line replaces the previous one, similar to tools like ``top``. Dependencies ------------ The tool requires: * Python 3 * The ``dpdk-telemetry.py`` script (in the same directory or in PATH) For monitoring, a DPDK application with telemetry enabled must be running, though the watcher can start before the application and will connect automatically.