/doca-telemetry-utils

license: Apache-2.0
name: doca-telemetry-utils
description: >
  doca_telemetry_utils command line on a host with DOCA: discover the
  diagnostic-counter schema, translate counter names to binary Data IDs
  and back, and check per-device counter support before committing a DOCA
  Telemetry exporter config. Use this skill when telemetry counters vanish
  between the exporter and the collector: "my exporter ships but the
  collector sees nothing", "this metric silently drops downstream", "which
  counters does this BlueField expose", "translate this 0x... back to a
  counter name", "what do node / pcie_index / depth mean here", or "is
  this counter supported on this device", even without naming the tool.
  Route exporter or collector code to doca-telemetry-exporter /
  doca-telemetry, DTS deployment to doca-dts, and DOCA install or repair
  to doca-setup.
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: tool
  doca_version: "3.5"
  tags:
    - doca
    - telemetry
    - tools
compatibility: >
  Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu
  22.04/24.04 or RHEL/SLES) with the Telemetry optional component and a
  BlueField DPU visible to DOCA on a known PCI address. Invokes
  /opt/mellanox/doca/tools/doca_telemetry_utils; per-device probe
  typically requires elevated privileges. The validation steps require a
  live DOCA install.

DOCA Telemetry Utils

Examples

• **"Which diagnostic counters does this BlueField actually

expose?"** — this is in scope. Enumerate then probe; do not start a collector app here.

• **"My exporter names `port_rx_bytes` but nothing shows up

downstream."** — translate name to Data ID and probe per-device support before changing the exporter.

Quick triage: the exporter ships, the collector sees nothing

1. `doca_telemetry_utils get-counters`: is the counter known to this release? 2. `doca_telemetry_utils <counter>`: print its property options. 3. `doca_telemetry_utils <counter> <properties>`: resolve the Data ID. 4. `doca_telemetry_utils <device PCI> <counter> <properties>`: "not supported" on this device means the exporter drops it silently; do not commit that counter. 5. `doca_telemetry_utils <0x... Data ID>`: reverse-resolve an ID captured on the wire. 6. Check host and BlueField release pairing with `doca-version`. 7. If every step resolves cleanly, hand off to `doca-telemetry` `## debug`.

Quote the tool's output verbatim; never construct Data IDs by hand.

Instructions

Follow Loading order below. Open the tasks companion for install / run / test. Open the capabilities companion for schema discovery and pairing with the telemetry libraries. Do not open every companion file.

**Where to start:** This is a tool skill for invoking `doca_telemetry_utils` — the documented host-side CLI that supports a DOCA Telemetry exporter / collector pipeline by discovering the counter schema, translating counter names ↔ Data IDs, and probing per-device counter support. Open the tasks companion and start at `## install` for the host-side prerequisites and `## run` for the three documented invocation classes (enumerate / name→ID / ID→name). Open the capabilities companion when the question is *what does this tool actually discover about the telemetry schema*, *how does it pair with the developer-side `doca-telemetry/SKILL.md` and exporter libraries*, *how do I confirm a device supports a counter before committing an exporter config to it*, or *why does my exporter pipeline silently drop a metric*.

**How to use this skill.** Read this file, then search the companion file for the `## <name>` heading the question needs and read that whole section. Answer completely from it, quoting only its symbols and commands. Do not browse docs; use the entry points in `doca-public-knowledge-map`. Give environment checks as commands for the user's DOCA host. For out-of-scope requests, name the skill that owns them and stop.

This skill is the **operator-side support tool** for a DOCA Telemetry deployment. It is NOT the developer-side collector library (that is `doca-telemetry/SKILL.md`), NOT the developer-side publisher library (that is `doca-telemetry-exporter` — see `doca-telemetry ## Related skills` (`doca-telemetry/SKILL.md#related-skills`)), and NOT a DOCA Telemetry Service (DTS) deployment guide (route to `doca-dts`). Three separate surfaces; conflating them is the most common telemetry first-touch error.

Example questions this skill answers well

The CLASSES of `doca_telemetry_utils` questions this skill is built to answer, each with one worked example. The class is the load-bearing piece; the worked example is one instance.

• **"My exporter says it's emitting `port_rx_bytes` but

nothing shows up downstream — what did I get wrong?"** — worked example: *"my exporter config has a counter name string and my collector sees no events with that name"*. Answered by the name ↔ Data ID translation step in the capabilities companion

• the per-device-support probe in

the tasks companion: the exporter ships a Data ID, not a name; a name in the config that resolves to a Data ID the device does not support is silently dropped.

• **"Which DOCA diagnostic counters does this BlueField

actually expose?"** — worked example: *"enumerate the full counter schema for my BlueField-3 before I write the exporter config"*. Answered by the schema-discovery invocation class in the capabilities companion (`doca_telemetry_utils get-counters` lists every counter name the diagnostic-data surface knows about; pair with a per-device probe to confirm support).

• **"I have a Data ID in a captured log — what counter

was that?"** — worked example: *"a downstream consumer emitted `Data ID: 0x1160000600030201` — translate it back so I can correlate against the public guide"*. Answered by the reverse-resolve invocation class in the capabilities companion

• the

ID-encodes-properties rule in the tasks co