On Thu, 15 Jan 2026 19:03:24 +0000 Bruce Richardson <[email protected]> wrote:
> TL;DR > ------ > > For a quick demo, apply patches, run e.g. testpmd and then in a separate > terminal run: > > ./usertools/dpdk-telemetry-watcher.py -d1T eth.tx > > Output, updated once per second, will be traffic rate per port e.g.: > > Connected to application: "dpdk-testpmd" > Time /ethdev/stats,0.opackets /ethdev/stats,1.opackets Total > 16:29:12 5,213,119 5,214,304 10,427,423 > > > Fuller details > -------------- > > While we have the dpdk-telemetry.py CLI app for interactive querying of > telemetry on the commandline, and a telemetry exporter script for > sending telemetry to external tools for real-time monitoring, we don't > have an app that can print real-time stats for DPDK apps on the > terminal. This patchset adds such a script, developed with the help of > Github copilot to fill a need that I found in my testing. Submitting it > here in the hopes that others find it of use. > > The script acts as a wrapper around the existing dpdk-telemetry.py > script, and pipes the commands to that script and reads the responses, > querying it once per second. It takes a number of flag parameters, such > as the ones above: > - "-d" for delta values, i.e. PPS rather than total packets > - "-1" for single-line output, i.e. no scrolling up the screen > - "-T" to display a total column > > Other flag parameters can be seen by looking at the help output. > > Beyond the flags, the script also takes a number of positional > parameters, which refer to specific stats to display. These stats must > be numeric values, and should take the form of the telemetry command to > send, followed by a "." and the stat within the result which is to be > tracked. As above, a stat would be e.g. "/ethdev/stats,0.opackets", > where we send "/ethdev/stats,0" to telemetry and extract the "opackets" > part of the result. > > However, specifying individual stats can be awkward, so some shortcuts > are provided too for the common case of monitoring ethernet ports. Any > positional arg starting with "eth" will be replaced by the set of > equivalent values for each port, e.g. "eth.imissed" will track the > imissed value on all ports in use in the app. The ipackets and opackets > values, as common metrics, are also available as shortened values as > just "rx" and "tx", so in the example above, "eth.tx" means to track the > opackets stat for every ethdev port. > > Finally, the script also has reconnection support so you can leave it > running while you start and stop your application in another terminal. > The watcher will try and reconnect to a running instance every second. > > v3: > Updated following AI review > - removed unnecessary f-string > - added documnentation in guides/tools > - added release note entry > > v2: > - improve reconnection handling, eliminating some crashes seen in testing. > > > Bruce Richardson (7): > usertools: add new script to monitor telemetry on terminal > usertools/telemetry-watcher: add displaying stats > usertools/telemetry-watcher: add delta and timeout opts > usertools/telemetry-watcher: add total and one-line opts > usertools/telemetry-watcher: add thousands separator > usertools/telemetry-watcher: add eth name shortcuts > usertools/telemetry-watcher: support reconnection > > doc/guides/rel_notes/release_26_03.rst | 7 + > doc/guides/tools/index.rst | 1 + > doc/guides/tools/telemetrywatcher.rst | 184 +++++++++++ > usertools/dpdk-telemetry-watcher.py | 435 +++++++++++++++++++++++++ > usertools/meson.build | 1 + > 5 files changed, 628 insertions(+) > create mode 100644 doc/guides/tools/telemetrywatcher.rst > create mode 100755 usertools/dpdk-telemetry-watcher.py > > -- > 2.51.0 AI also had some good feedback on the documentation here. ### Spelling Issues ✓ No spelling errors found. --- ### Grammar Issues | Line/Section | Issue | Suggestion | |--------------|-------|------------| | Options: `-i` | "...when multiple applications are running with the same file-prefix." | Consider: "...when multiple applications **share** the same file-prefix." (more concise) | | Options: `-t` | "Number of iterations to run before stopping." | Should be: "Number of iterations to run before **exiting**." (matches the behavior—tool exits, not just stops) | | Statistics Format | "To discover available commands and fields:" followed by numbered list | The colon introduces an incomplete sentence. Better: "To discover available commands and fields, use the following methods:" or remove the colon and use "you can:" | --- ### Technical Writing Style Issues | Location | Issue | Recommendation | |----------|-------|----------------| | Title | "dpdk-telemetry-watcher Application" | Consider: "dpdk-telemetry-watcher Tool" — the word "application" might confuse readers since DPDK applications are the *targets* being monitored | | Opening paragraph | "Data Plane Development Kit (DPDK)" | Unnecessary expansion—DPDK docs assume readers know what DPDK is. Simplify to just "DPDK" | | Options: `-d` | "Display delta (incremental) values" | Redundant parenthetical. Use either "delta values" or "incremental values", not both | | Options: `-d` | "which is useful for monitoring rates of change" | Vague. Better: "which is useful for monitoring per-second rates" | | Shortcuts section | "These shortcuts automatically detect all available ethernet devices" | Should be "Ethernet" (capital E) per DPDK style, or better: "ethdev ports" to match DPDK terminology | | Output Format | "Values are formatted with locale-specific number formatting (e.g., comma separators)." | Awkward repetition of "formatting". Rewrite: "Values use locale-specific formatting (e.g., comma as thousands separator)." | | Dependencies | "A running DPDK application with telemetry enabled" | Contradicts the "Running the Application" section which says the tool "can be run at any time, whether or not a DPDK application is currently running." Remove this item or clarify it's needed for actual monitoring. | --- ### Passive Voice (per DPDK documentation standards) | Location | Passive Construction | Active Alternative | |----------|---------------------|-------------------| | Opening | "Statistics are specified in the format..." | "Specify statistics in the format..." | | Output Format | "Values are formatted with..." | "The tool formats values with..." | | Output Format | "the tool displays the change in each statistic" | ✓ Already active (good) | --- ### Consistency Issues | Issue | Details | |-------|---------| | "ethernet" vs "Ethernet" | Line uses lowercase "ethernet devices" — DPDK typically uses "Ethernet" or avoids it entirely in favor of "ethdev" | | "file-prefix" hyphenation | Used consistently (good), but DPDK code often uses "file_prefix" — verify against dpdk-telemetry.py docs | | Option argument style | Mix of `FILE_PREFIX` (all caps) and `TIMEOUT` (all caps) — consistent (good) | | Example commands | Some use full paths (`/ethdev/stats,0.ipackets`), shortcuts (`eth.rx`) — good variety showing both | --- ### RST Formatting Issues | Location | Issue | Fix | |----------|-------|-----| | Line 1 | `.. SPDX` has two spaces after `..` | Should be single space: `.. SPDX` | | Cross-references | `` `Statistics Format`_ `` and `` `Examples`_ `` | These RST references work but would be more robust as `:ref:` targets for cross-document linking | --- ### Missing Information | Gap | Suggestion | |-----|------------| | No mention of Ctrl+C | Add note that Ctrl+C cleanly exits the monitoring loop (already in code) | | No sample output | Consider adding a brief example of what the output looks like | | No error handling description | What happens if a stat doesn't exist? Document the error messages | --- ### Suggested Rewrites **Opening paragraph** (current): > The ``dpdk-telemetry-watcher`` tool is a Data Plane Development Kit (DPDK) > utility that provides continuous monitoring of DPDK telemetry statistics on > the command line. It wraps the ``dpdk-telemetry.py`` script to provide > real-time statistics display capabilities. **Suggested**: > The ``dpdk-telemetry-watcher`` tool monitors DPDK telemetry statistics > continuously on the command line. It wraps ``dpdk-telemetry.py`` to provide > real-time display of selected statistics. --- **Dependencies section** (current): > The tool requires: > * Python 3 > * The ``dpdk-telemetry.py`` script must be available in the same directory or > in the system PATH > * A running DPDK application with telemetry enabled **Suggested**: > 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. --- ### Summary | Category | Count | |----------|-------| | Grammar issues | 3 | | Style issues | 7 | | Passive voice | 2 | | Consistency issues | 1 | | RST formatting | 1 | | Missing information | 3 | **Overall**: The documentation is functional and reasonably clear. The issues are minor and mostly stylistic. The most important fix is resolving the contradiction in the Dependencies section about whether a running DPDK application is required.
