7. 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.

7.1. 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:

dpdk-telemetry-watcher.py [options] stat1 stat2 ...

7.2. Options

-h, --help

Display usage information and quit

-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.

-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.

-l, --list

List all possible file-prefixes and exit. This is useful to discover which DPDK applications are currently running.

-t TIMEOUT, --timeout TIMEOUT

Number of iterations to run before exiting. If not specified, the tool runs indefinitely until interrupted with Ctrl+C.

-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.

-T, --total

Display a total column at the end of each row that sums all monitored statistics.

-1, --single-line

Display output on a single line, replacing the previous output. This is useful for reducing scrolling and keeping the display compact.

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.

7.3. 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.

7.4. 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.

7.5. 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

7.6. 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.

7.7. 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.