/doca-telemetry-utils

license: Apache-2.0
name: doca-telemetry-utils
description: >
  Use this skill when the user is invoking `doca_telemetry_utils` on
  a host with DOCA installed — discovering the diagnostic-counter
  schema, translating counter names to binary Data IDs, validating
  per-device counter support before committing a DOCA Telemetry
  exporter config, or reverse-resolving a captured Data ID. Trigger
  even when the user does not explicitly mention "doca_telemetry_utils"
  or "Data ID" — typical implicit phrasings include "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 before
  I commit it". Refuse and route elsewhere for developer-side collector
  / exporter library programming, DTS deployment, or DOCA install /
  repair — those belong to doca-telemetry, doca-public-knowledge-map,
  and doca-setup.
metadata:
  kind: tool
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.

DOCA Telemetry Utils

**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 [`TASKS.md`](TASKS.md) and start at [`## install`](TASKS.md#install) for the host-side prerequisites and [`## run`](TASKS.md#run) for the three documented invocation classes (enumerate / name→ID / ID→name). Open [`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what does this tool actually discover about the telemetry schema*, *how does it pair with the developer-side [`doca-telemetry`](../../libs/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*.

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`](../../libs/doca-telemetry/SKILL.md)), NOT the developer-side publisher library (that is `doca-telemetry-exporter` — see [`doca-telemetry ## Related skills`](../../libs/doca-telemetry/SKILL.md#related-skills)), and NOT a DOCA Telemetry Service (DTS) deployment guide (route via [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md)). 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 [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the per-device-support probe in

[`TASKS.md ## test`](TASKS.md#test): 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 [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) (`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 [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the

ID-encodes-properties rule in [`TASKS.md ## use`](TASKS.md#use) (a Data ID carries the counter's property dimensions; the reverse-resolve reports them).

• **"What property dimensions does this counter take and

what values are valid?"** — worked example: *"I know the counter is `pcie_link_write_stalled_time_*` — what do `node` / `pcie_index` / `depth` mean and what values does the device accept?"*. Answered by the property-dimension table in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the `<name>` invocation without arguments which

prints the documented property options + units + unit-specific axes.

• **"Is this counter supported on this device before I

commit it to the exporter config?"** — worked example: *"validate that `port_rx_bytes` with `node=1` is exposed on the BlueField at PCIe address X before I write the exporter config"*. Answered by the per-device-support probe (`<device PCI> <name> [properties]`) in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the gate-before-commit rule in

[`TASKS.md ## use`](TASKS.md#use).

• **"Is `doca_telemetry_utils` on my install, and is it

paired with the matching `doca-telemetry` library version?"** — worked example: *"is the diagnostic- data counter set my exporter targets on this DOCA vers