---

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 and start at ## install for the host-side prerequisites and ## run for the three documented invocation classes (enumerate / name→ID / ID→name). Open 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 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), NOT the developer-side publisher library (that is doca-telemetry-exporter — see doca-telemetry ## Related skills), and NOT a DOCA Telemetry Service (DTS) deployment guide (route via doca-public-knowledge-map). 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
  • the per-device-support probe in 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 (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
  • the ID-encodes-properties rule in 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
  • 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
  • the gate-before-commit rule in 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 version?". Answered by the version-overlay in CAPABILITIES.md ## Version compatibility, which redirects to the canonical doca-version chain and adds the tool ↔ doca-telemetry library schema-version match rule.

Audience

This skill serves external operators, developers, and AI agents standing up or debugging a DOCA Telemetry exporter / collector pipeline who need to confirm the counter schema, validate per-device support, or translate between human-readable counter names and the binary Data IDs the exporter actually ships. Concretely:

• A platform operator standing up a new DOCA Telemetry exporter on a BlueField fleet who needs to confirm which counters the target devices actually expose before committing the exporter config.
• A developer of a downstream consumer (a collector app linking doca-telemetry, or a third-party aggregator consuming via DTS) who has a captured Data ID stream and needs to translate IDs back to counter names + properties.
• An operator debugging a "nothing is shipping downstream" / "this metric is silently missing" report against a deployed exporter — the schema-discovery + per-device-support probes are the canonical "is the counter even supposed to work on this device" first step before suspecting the collector or the network path.
• An AI agent producing a "validated exporter config for this BlueField + this DOCA version" answer honestly — with each counter resolved to its Data ID and each Data ID confirmed against the per-device capability probe.

It is not for users debugging the doca_telemetry_utils binary itself, not a substitute for the live public DOCA Telemetry guides, and not the right place for learning how to write an exporter application (that audience belongs in doca-telemetry-exporter skill when present, or via doca-public-knowledge-map).

The tool is shipped as a CLI binary under /opt/mellanox/doca/tools/, not a library you link against. The skill uses the same kind: tool three-file shape as the rest of the bundle so the agent's task-verb contract is uniform across libraries, services, and tools.

Language scope

doca_telemetry_utils is a C host-side CLI that uses the documented doca_telemetry_diag surface to list counter types and probe per-device support. Its inputs are command-line arguments (counter name, property values, Data ID, optional device PCI address); its outputs are human-readable Data ID + properties mappings. The skill keeps workflow guidance language- neutral; downstream consumers in any language can use the resolved Data IDs against their own collector code.

When to load this skill

Load this skill when the user is — or the agent needs to — invoke doca_telemetry_utils on a real host with DOCA installed, alongside an exporter / collector pipeline that needs schema discovery, per-device support validation, or Data ID translation. Concretely:

• Enumerating the full counter schema before writing a fresh DOCA Telemetry exporter config (get-counters).
• Validating that a chosen counter + property set resolves to a Data ID the target device actually supports, before committing the config.
• Reverse-resolving a Data ID captured from a downstream consumer back to a counter name + properties for correlation against the public guide.
• Debugging a "exporter ships, collector receives nothing" report (the canonical schema-mismatch / unsupported-counter failure mode).
• Producing a "validated counter set for this BlueField + this DOCA version" artifact as part of a structured exporter-config baseline.
• Migrating an exporter pipeline across DOCA versions and confirming each previously-supported counter still resolves cleanly on the new version.

Do not load this skill for general DOCA orientation, collector / exporter library programming, DTS deployment, or DOCA install. For those, route to doca-public-knowledge-map, doca-telemetry, or doca-setup.

What this skill provides

This is a thin loader. Substantive material lives in two companion files:

• CAPABILITIES.md — what doca_telemetry_utils discovers + how it pairs with the developer-side surfaces: the three documented invocation classes (enumerate / name→ID / ID→name), the property- dimension model (counters carry property axes such as node, pcie_index, depth, plus per-unit axes), the optional per-device capability probe (<device PCI> <name> runs the resolved counter against the device), the operator-side support role (this is NOT the developer-side library; it exists to make exporter / collector setups honest), the version overlay (tool ↔ doca-telemetry library schema version pairing), the layered error taxonomy (install / parse / unknown-counter / unknown-data-id / property-out- of-range / device-not-supported / version / cross-cutting), the observability surface (stdout-only), and the safety policy (the tool is read-only; mistakes appear downstream as silent metric drops, not crashes).
• TASKS.md — step-by-step workflows for the in-scope task verbs: install (host-side DOCA + telemetry component prerequisites), configure (axis decisions: which invocation class, which device, which counter), build (route to install — the binary is shipped), modify (refuse — do not patch the binary; modify the invocation and the exporter / collector config that consumes the resolved Data IDs), run (the three documented invocations), test (round-trip a chosen counter through name → Data ID → per-device probe → exporter config → collector receipt), debug (walk th