[PATCH v3 0/7] Add script for real-time telemetry monitoring

[Stephen Hemminger]

On Thu, 15 Jan 2026 19:03:24 +0000
Bruce Richardson <bruce.richardson at intel.com> 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.