AutoGineer
Generated banner for Doca Telemetry Utils
Generated logo for Doca Telemetry Utils

Doca Telemetry Utils

NVIDIAOfficialCreated by NVIDIA

  • Skill
  • Tool integration
  • Cloud and DevOps
  • Apache-2.0
  • Medium risk
Download ZIP

From the author

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.
— the description by NVIDIA

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The doca-telemetry-utils skill provides guidance for using the host-side command line tool of the same name. It is designed to assist operators in managing DOCA Telemetry pipelines by bridging the gap between exporter configurations and collector visibility. The tool enables users to enumerate diagnostic counters, translate between human-readable counter names and binary Data IDs, and verify whether specific hardware devices support particular counters. This skill serves as a diagnostic aid to resolve issues where telemetry data is missing or silently dropped, ensuring that exporter configurations are valid for the target BlueField DPU environment.

What it does

  • Enumerates the diagnostic-counter schema available on a DOCA-enabled host.
  • Translates between human-readable counter names and binary Data IDs.
  • Probes per-device counter support to validate exporter configurations.
  • Reverse-resolves captured Data IDs to identify specific counters and properties.
  • Provides diagnostic information to troubleshoot silent metric drops in telemetry pipelines.

When to use it

  • When telemetry counters are missing or not appearing in the collector.
  • Before committing a new DOCA Telemetry exporter configuration to ensure device support.
  • When needing to correlate captured binary Data IDs with public documentation.
  • During migration of telemetry pipelines across different DOCA versions.
  • When debugging why specific metrics are being silently dropped downstream.

Advantages

  • Enables proactive validation of telemetry configurations before deployment.
  • Reduces troubleshooting time for silent data loss in telemetry pipelines.
  • Provides an authoritative, version-specific source of truth for counter schemas.
  • Facilitates accurate correlation between captured logs and counter definitions.

Usage examples

“Which diagnostic counters does this BlueField actually expose?”
The agent will guide the user to run the enumeration command to list all available counter names for the specific BlueField device.
“My exporter is configured for port_rx_bytes but the collector sees nothing. How do I check this?”
The agent will assist in translating the counter name to a Data ID and running a per-device probe to confirm if the hardware supports that counter.
“I have a captured Data ID 0x1160000600030201. What counter is this?”
The agent will instruct the user to use the reverse-resolve invocation to map the binary ID back to its corresponding counter name and property dimensions.
“Is port_rx_bytes with node=1 supported on my device?”
The agent will help the user execute a per-device capability probe to validate the specific counter and property combination against the target PCIe address.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/nvidia/doca-telemetry-utils/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip doca-telemetry-utils.zip -d .agents/skills

Documentation by NVIDIA

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 companion (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 the capabilities companion

    • 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 the capabilities companion

    • the gate-before-commit rule in the tasks companion.

  • "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 the capabilities companion, which redirects to the canonical doca-version/SKILL.md chain and adds the tool ↔ doca-telemetry library schema-version match rule.

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/SKILL.md, doca-telemetry/SKILL.md, or doca-setup/SKILL.md.

What this skill provides

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

  • the capabilities companion — 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).

  • the tasks companion — 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 the error taxonomy), use (the hand-off into the developer-side doca-telemetry collector / exporter pipeline), plus a Deferred task verbs block.

The skill assumes a host where DOCA is already installed with the telemetry component, a BlueField the operator is targeting is visible to DOCA, and the exporter / collector pipeline that consumes the resolved Data IDs is either being authored or has already been authored against the matching doca-telemetry/SKILL.md library version.

What this skill deliberately does not ship

This skill is agent guidance, not a samples or scripts bundle. To keep the boundary clean, it deliberately does not contain — and pull requests should not add:

  • A verbatim counter inventory or Data ID table. The counter set evolves across DOCA versions and BlueField generations; an inventory pinned in this skill would silently rot. doca_telemetry_utils get-counters on the installed binary is the authoritative source.

  • Pre-baked exporter / collector configs. Configs are install-, device-, and use-case-specific; a packaged config in this skill would mislead operators on a different setup.

  • A DTS deployment recipe. DTS is a separate DOCA service with its own public guide; route via doca-public-knowledge-map/SKILL.md. This skill resolves the counter names + IDs a DTS pipeline consumes; it does not configure DTS.

  • Wrappers, parsers, or scripts in any language that consume the tool's output. The output is a simple text mapping; users who want to script against it should read the live guide and write the parser against their installed version.

  • A samples/ or reference/ subtree. This is a thin loader for a shipped CLI; substantive material lives on the public page, in --help, and in doca-telemetry/SKILL.md.

Loading order

  1. Read this skill first to confirm the user's question is in scope (operator-side support tooling for a telemetry pipeline, not the developer-side library programming).

  2. For the three invocation classes, the property-dimension model, the per-device support probe, the version overlay, the error taxonomy, the observability surface, and the safety policy, see the capabilities companion.

  3. For the documented invocations and the discover → resolve → validate → consume workflow — install, configure, build, modify, run, test, debug, use — see the tasks companion.

Related skills

  • doca-telemetry/SKILL.md — the developer-side collector library whose schema this tool helps the operator discover. Pair them in every exporter-pipeline triage session. The collector library skill teaches the collector-vs-exporter rule, the schema-must-match contract with the publisher, and the consumer- queue-full back-pressure rule; this tool's role is to make the schema half of that contract inspectable from the operator side. Conflating the library and the tool is the most common telemetry first-touch error.

  • doca-public-knowledge-map/SKILL.md — routing to the public DOCA Telemetry guide and the DOCA Telemetry Service (DTS) page on docs.nvidia.com, plus the on-disk install layout for the tool.

  • doca-version/SKILL.md — canonical DOCA version-handling rules. The ## Version compatibility section in the capabilities companion is a concise overlay that redirects here for the body and adds the tool ↔ doca-telemetry library schema-version pairing rule.

  • doca-setup/SKILL.md — env preparation, install verification, and the I have no install yet path with the public NGC DOCA container. This skill assumes its preconditions are satisfied (DOCA installed with the telemetry component, BlueField visible to DOCA).

  • doca-debug/SKILL.md — the cross-cutting debug ladder. Telemetry-utils feeds the cross-cutting ladder by surfacing the counter schema + per-device support truth at the runtime layer; exporter-pipeline regressions often resolve at the schema layer before touching the collector / network path.

  • doca-structured-tools-contract/SKILL.md — the bundle's detect → prefer → fall back → report contract for structured helper tools. The command appendix in the tasks companion honors this contract.

  • doca-programming-guide/SKILL.md — general DOCA programming patterns shared by every library / tool surface, including the cross-library DOCA_ERROR_* taxonomy this tool's host-side error layer overlays on top of when downstream collector / exporter code surfaces a related error.

Files

CAPABILITIES.md

DOCA Telemetry Utils — Capabilities

Where to start: doca_telemetry_utils is the operator-side support tool for a DOCA Telemetry exporter / collector pipeline. The pattern overview below names the recurring doca_telemetry_utils-class questions. Pick the pattern first, then drill into the H2 that owns the substance. For the how of executing each pattern, jump to TASKS.md.

This file is loaded by SKILL.md. It documents what the tool discovers about the diagnostic-counter schema, its three documented invocation classes, the property-dimension model counters carry, the optional per-device capability probe, the version overlay against the developer-side doca-telemetry/SKILL.md library, the layered error and observability surfaces, and the safety posture (the tool is read-only; operator mistakes show up downstream as silent metric drops, not as crashes). For step-by-step invocations and the discover → resolve → validate → consume workflow, see TASKS.md.

Pattern overview

Every doca_telemetry_utils-class question this skill teaches resolves into one of SIX patterns. The patterns are CLASSES — they apply across every BlueField the tool can probe and every DOCA Telemetry pipeline shape, not just one.

doca_telemetry_utils patternClass shapeWhere the substance lives
1. Discover the counter schemaEnumerate every counter name the DOCA diagnostic-data surface knows about, before committing exporter / collector config. doca_telemetry_utils get-counters is the enumeration entrypoint.## Capabilities and modes invocation-class table + TASKS.md ## run step 1
2. Resolve name → Data ID + propertiesTranslate a human-readable counter name into the binary Data ID an exporter actually ships, with the documented property dimensions (node, pcie_index, depth, …). The exporter publishes IDs, not names; a name in the config that resolves to the wrong ID is silently dropped downstream.## Capabilities and modes invocation-class table + TASKS.md ## run step 2
3. Reverse-resolve Data ID → name + propertiesTranslate a captured Data ID from a downstream consumer back to its counter name + properties, for correlation against the public DOCA Telemetry guide or against the exporter's source-of-truth config.## Capabilities and modes invocation-class table + TASKS.md ## run step 3
4. Validate per-device supportRun the resolved counter against a specific device's capability surface (<device PCI> <name> [properties]) before committing it to an exporter config. A counter that resolves cleanly but is not supported on the target device produces no metric.## Capabilities and modes per-device-probe rule + TASKS.md ## test validation gate
5. Diagnose a silent metric dropA downstream consumer reports a metric missing; the exporter says it's emitting. Walk the schema-mismatch / unsupported-counter error taxonomy in ## Error taxonomy before suspecting the collector or network path.## Error taxonomy + TASKS.md ## debug
6. Bake a validated exporter configThe hand-off into the developer-side pipeline. Each counter the operator wants in the exporter config is first run through name → ID → per-device probe; the resulting validated tuple is the artifact the exporter config references.TASKS.md ## use hand-off + doca-telemetry/SKILL.md for the consumer side

Two cross-cutting rules that apply to every pattern above:

  • The exporter ships Data IDs, not names. Operator- side confusion between "the human-readable counter name" and "the Data ID the exporter actually publishes" is the most common silent-metric-drop failure mode. The agent's rule: every counter in an exporter config is resolved through this tool before the config is deployed, and the resolved Data ID is the canonical reference in the config.

  • Per-device support is not assumed from the schema. The diagnostic-counter schema is what DOCA knows about; per-device support is what this BlueField at this firmware actually exposes. The two are not the same; the operator's rule for any exporter config is to validate each counter against the device's capability surface before committing.

Capabilities and modes

doca_telemetry_utils is shipped as a single CLI binary under /opt/mellanox/doca/tools/ on every DOCA install that includes the Telemetry optional component. It is a read-only CLI; it does not configure DTS, write exporter configs, or ship telemetry itself. Its job is the schema-discovery + per-device-support question — the operator-side knowledge that exporter / collector setups need to be honest.

Three documented invocation classes. Per the public DOCA Telemetry Utils guide:

Invocation classShapeWhat it produces
Enumerate the schemadoca_telemetry_utils get-countersPrints every counter name the DOCA diagnostic-data surface knows about on this install. The output is the catalog of what DOCA understands; per-device support is checked separately.
Resolve name → Data IDdoca_telemetry_utils [<device PCI>] <name> [relevant properties]Resolves the counter name + property values to a Data ID, prints the Data ID + name + unit + property values. If <device PCI> is provided, also probes the device's support for the resolved Data ID. Running <name> alone prints the documented property options for that counter.
Reverse-resolve Data ID → namedoca_telemetry_utils [<device PCI>] <DATA_ID>Reverse-resolves the Data ID to a counter name + unit + property values. If <device PCI> is provided, also probes the device's support.

Running the tool with no arguments prints a help banner; the exact subcommand strings and option names are authoritative on --help on the installed version and on the public DOCA Telemetry guide.

Property-dimension model. Diagnostic counters carry documented property dimensions; the same counter name can resolve to different Data IDs depending on which property values the operator picks. The general property axes (re-verify against --help on the installed binary):

Property axisWhat it picks
nodeWhich logical node the counter is reported against — e.g. a per-port counter has a node that selects which port.
pcie_indexWhich PCIe interface the counter refers to — e.g. for pcie_link_* counters that distinguish between the device's PCIe ports / lanes.
depthWhich depth (0-63) the counter refers to. In DOCA 3.5, node, pcie_index, and depth are fields encoded in the pcie_link_* Data IDs; they are not a queue-depth condition.
Unit-specific axes (per the counter's Unit: line)Each counter belongs to a Unit (e.g. PCIE, the host-RX-transport group, the TX-port group); each unit can expose unit-specific property axes beyond the generic three.

A worked example (counter name and Data ID from the public DOCA Telemetry Diag counter list; re-verifiable on a local DOCA install):

$ doca_telemetry_utils pcie_link_write_stalled_time_no_posted_header_credits_ns 1 2 3
Data ID: 0x1160000600030201
Name: pcie_link_write_stalled_time_no_posted_header_credits_ns
Unit: PCIE
node: 1
pcie_index: 2
depth: 3

Caveat (DOCA 3.5, known issue 4046180). For pcie_link_* Data IDs that take node, pcie_index, and depth, the only valid values today are 0 0 0. The 1 2 3 example above only shows how the Data ID is encoded; use 0 0 0 when sampling a real pcie_link_* counter.

The agent's rule for any counter the operator names: run doca_telemetry_utils <name> once without properties to print the documented property options for that counter, then re-run with the chosen properties to resolve the Data ID. Inventing property values from generic CLI knowledge is the canonical hallucination failure for this skill.

Counter catalog scope. The schema the tool exposes is the DOCA Telemetry diagnostic-data surface (the doca_telemetry_diag API on the developer side). The documented surface covers RX / TX port counters, host RX / TX transport-layer counters, PCIe link counters, completion-engine counters, ICMC counters, sensor counters (voltage / current / power / temperature), and other groups documented in the public DOCA Telemetry guide. The exact counter set evolves across DOCA versions; the agent does NOT enumerate it from memory.

Optional per-device capability probe. Whenever <device PCI> is provided as the first argument, the tool runs the resolved counter against the device's capability surface. The two pieces of information the tool returns:

  • The resolved Data ID + name + unit + property values (the schema-side answer).

  • Whether the device supports the resolved Data ID (the per-device answer).

A counter that resolves on the schema but is not supported on the device produces no metric when the exporter ships it. The agent's rule for every counter that will be committed to an exporter config: run the per-device probe with the target device's PCI address, and only commit if the device supports the Data ID.

What this tool deliberately does not do. The tool is read-only; the operator-side support role is schema discovery + per-device support probing, not exporter configuration, not DTS deployment, not metric shipping. Once the operator has the validated Data ID for each counter, the hand-off is into the developer-side doca-telemetry/SKILL.md collector or the exporter library that consumes the IDs.

Version compatibility

For the canonical DOCA version-detection chain, the four-way match rule, NGC container semantics, and the headers-win-over-docs rule, see doca-version/SKILL.md. The body lives there; this skill does not duplicate it.

The doca_telemetry_utils-specific overlay is:

  • Tool ↔ library schema-version pairing. The tool resolves names ↔ Data IDs against the doca_telemetry_diag schema the host-side DOCA install carries; the developer-side doca-telemetry/SKILL.md library consumes those Data IDs. The two must come from the same DOCA release band per the doca-version CAPABILITIES.md ## Version compatibility (doca-version/CAPABILITIES.md#version-compatibility) four-way match rule, OR the exporter / collector pipeline can ship Data IDs the consumer's library does not understand.

  • The counter catalog is install-versioned. New DOCA versions add new counters; some older counters can be renamed or have new property dimensions added. The agent's rule when migrating an exporter config across DOCA versions: re-resolve every counter in the config against the new install's doca_telemetry_utils get-counters, before deploying. A name that resolved on the old install is not guaranteed to resolve identically on the new install.

  • Per-device support is install + firmware versioned. Even at the same DOCA version, two BlueField generations or two firmware levels can differ on which counters are exposed. The per- device probe (<device PCI>) is the runtime authority on top of the schema-side catalog.

  • Public DOCA Telemetry page is the source of truth for the tool's command-line surface. When that page disagrees with this skill, the live guide wins.

Error taxonomy

doca_telemetry_utils's error surface spans the host install, command-line parse errors, schema-side "unknown counter" / "unknown Data ID" errors, property-value-out-of-range errors, per-device "not supported on this device" errors, the cross- cutting partial-install / mixed-version layer, and the downstream-pipeline (exporter / collector) errors the tool does NOT itself emit but routes to. The agent distinguishes these layers in escalating order; jumping layers wastes the user's time on the wrong fix.

  1. Install. The binary is missing from /opt/mellanox/doca/tools/, the Telemetry optional component is not installed, or the binary's loader-dependent shared libs are missing. Routing: route to doca-setup ## configure (doca-setup/TASKS.md#configure) to install / repair the host-side DOCA package selection; confirm the installed version per doca-version TASKS.md ## configure (doca-version/TASKS.md#configure).

  2. Parse. The invocation itself does not parse — unknown subcommand, missing required argument, Data ID in the wrong format (the documented format is 0x-prefixed hex). Routing: re-read --help on the installed binary and the public DOCA Telemetry guide; do not guess at the syntax.

  3. Unknown counter. The counter name passed does not exist in the schema on this DOCA version. Cause: typo, renamed counter across versions, or counter from a different group the user thought was supported. Routing: run doca_telemetry_utils get-counters to enumerate the actual set on this install; re-confirm against the public DOCA Telemetry guide for the version the user is targeting.

  4. Unknown Data ID. The Data ID passed for reverse-resolve does not exist in the schema on this DOCA version. Cause: the ID is from a different DOCA version, a typo, or was constructed by hand (Data IDs encode property values and must come from a forward resolve). Routing: cross-check the Data ID against a fresh forward resolve from the same DOCA version.

  5. Property-value-out-of-range. Counter is known, but a property value is outside the documented range. Cause: the operator passed node, pcie_index, depth, or a unit- specific axis value the documented set does not accept. Routing: run doca_telemetry_utils <name> without properties to print the documented options for that counter; re-run with a valid value.

  6. Device-not-supported. Counter resolves on the schema but the device probe (<device PCI>) reports the device does not support the resolved Data ID. Cause: BlueField generation, firmware level, or device configuration does not expose this counter. Routing: this is the answer the user came for — do NOT commit this counter to the exporter config for this device. Re-check the public DOCA Telemetry guide for the per-platform support matrix.

  7. Version. Cross-cutting partial-install / mixed-version per doca-version CAPABILITIES.md ## Version compatibility (doca-version/CAPABILITIES.md#version-compatibility). Symptoms: the tool's reported counter set disagrees with the developer-side doca-telemetry/SKILL.md library version's schema. Routing: walk doca-version TASKS.md ## debug (doca-version/TASKS.md#debug) end-to-end.

  8. Cross-cutting (downstream pipeline). The tool reports cleanly but the exporter / collector pipeline still fails to ship a metric. Cause is in the downstream pipeline, not in the telemetry-utils tool. Routing: hand off to doca-telemetry TASKS.md ## debug (doca-telemetry/TASKS.md#debug) for the collector-side ladder, plus doca-debug ## debug (doca-debug/SKILL.md) for the cross-cutting layers (driver, firmware, network).

doca_telemetry_utils does not itself participate in the cross-library DOCA_ERROR_* taxonomy that DOCA libraries return through their C API; it is a CLI driving the diagnostic-data surface. The cross-library taxonomy is owned by doca-programming-guide CAPABILITIES.md ## Error taxonomy (doca-programming-guide/CAPABILITIES.md#error-taxonomy).

Observability

doca_telemetry_utils's observability surface is stdout — the tool prints the resolved Data ID + counter name + unit + property values, or the enumerated counter set, in human-readable form. There is no file output, no daemon, no live-streaming mode.

  • Stdout. The primary surface. Per the public guide, the resolved output is the (Data ID, Name, Unit, property-axis values) tuple. Capture stdout for every invocation the operator commits to an exporter config; it is the audit trail.

  • Per-device probe outcome. When <device PCI> is provided, the printed tuple is the union of the schema-side answer and the device-side "supported" / "not supported" answer; the agent's rule is to preserve the entire output as evidence for the exporter config decision.

  • No structured output. The tool does not (per the public surface) emit JSON / CSV. Users who want a machine-parseable form should read the live guide and write the parser against their installed version, or use the structured helper per the doca-structured-tools-contract/SKILL.md preamble when present.

  • Captured-evidence tuple. The minimum metadata to attach to a validated counter committed to an exporter config: (DOCA version, BlueField identity + firmware, counter name, property values, resolved Data ID, per-device probe result). Without these, an exporter config cannot be regression-tested across DOCA upgrades.

For the cross-cutting env-side observability primitives (PCIe scans, devlink, mlxconfig), see doca-setup CAPABILITIES.md ## Observability (doca-setup/CAPABILITIES.md#observability). For the developer-side collector observability (per-consume status, schema-query, consumer-queue- full handling), see doca-telemetry CAPABILITIES.md ## Observability (doca-telemetry/CAPABILITIES.md#observability).

Safety policy

Overlay on the bundle-wide hardware-safety meta-policy. The rules below are this skill's per-artifact overlay on the cross-cutting rules in doca-hardware-safety CAPABILITIES.md ## Safety policy (doca-hardware-safety/CAPABILITIES.md#safety-policy) (specifically ### Per-artifact overlay pattern (doca-hardware-safety/CAPABILITIES.md#per-artifact-overlay-pattern)). When the two layers disagree, the stricter wins; when either layer says STOP, the agent stops.

doca_telemetry_utils is a read-only operator-side support tool. It does not load algorithms, configure firmware, or change device state. Its safety surface is instead about the downstream consequence of an operator decision the tool informs:

  • A wrong Data ID in an exporter config silently drops the metric. This is the load-bearing failure mode the tool exists to prevent. The agent's rule: every counter committed to an exporter config is first round-tripped through the tool (name → ID → per-device probe → commit), not committed from prose / blog / memory.

  • The schema-side answer is not the per-device answer. A counter that the schema knows about is not the same as a counter the target BlueField at this firmware level supports. The per-device probe (<device PCI>) is mandatory before committing a counter to an exporter config; skipping it is the canonical "my exporter ships nothing for this device" failure.

  • Re-resolve on DOCA version upgrades. When the user upgrades DOCA on the host, every counter in every exporter config must be re-resolved against the new install before the exporter pipeline is rolled forward. A counter that resolved on the old install is not guaranteed to resolve identically on the new install.

  • Telemetry data can leak operational information. Resolved counters and their reported values may surface workload-sensitive information (port utilization, retransmit counts, sensor readings); apply the operator's data-handling policy to the resolved-counter tuples + any captured downstream telemetry.

  • Do not invent counter names, Data IDs, or property values. The documented surface lives on the public DOCA Telemetry guide and in --help on the installed binary; prose-derived names / IDs / property values are the most common hallucination failure for this skill, and a wrong Data ID in an exporter config is exactly the kind of silent failure this tool exists to prevent.

This tool does NOT itself participate in the bundle-wide hardware-touching change classes (mlxconfig-class writes, firmware burns, BlueField mode flips); the meta-policy applies when the operator's downstream exporter / collector configuration touches those, in which case the hardware-safety overlays of the matching per-artifact skill (e.g. doca-pcc CAPABILITIES.md ## Safety policy (doca-pcc/CAPABILITIES.md#safety-policy) when telemetry sits next to PCC) take over.

Public-source pointer

The canonical public source for doca_telemetry_utils is the DOCA Telemetry page on docs.nvidia.com and the DOCA Telemetry Service (DTS) guide on the same site, reachable through doca-public-knowledge-map ## DOCA tools (doca-public-knowledge-map/SKILL.md#doca-tools) and doca-public-knowledge-map ## DOCA services (doca-public-knowledge-map/SKILL.md#doca-services). The public DOCA Telemetry Utils guide carries the three documented invocation classes. Do not invent counter names, Data IDs, property values, or unit-specific axes beyond what those public sources document, and re-verify against --help on the installed binary.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

The author says: 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.

Security

What our scanner noticed· Medium risk

  • Large base64-encoded blobs

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
NVIDIA
Publisher
NVIDIA (Official)
Source
NVIDIA/skills · skills/doca-telemetry-utils · commit fce3cca
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE-APACHE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by NVIDIA or NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download doca-telemetry-utils.zip