Skip to main content
skill CX Codex

doca-telemetry-utils — skill for Claude Code: DOCA counter diagnostics

A skill for Claude Code and Codex that runs doca_telemetry_utils on a host with DOCA to track where telemetry metrics disappear between exporter and collector.

Apache-2.0 ★ 4,106 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add NVIDIA/skills --skill doca-telemetry-utils -a claude-code
Open on GitHub

What doca-telemetry-utils does

The skill invokes the doca_telemetry_utils command line and solves three problems: enumerate available diagnostic counters for a BlueField, translate a counter name to its Data ID (and reverse-resolve an ID from logs), check whether a specific device supports a counter with given properties.

Requires DOCA SDK installed on Linux (Ubuntu 22.04, 24.04, or RHEL/SLES) with the Telemetry component in /opt/mellanox/doca, a visible BlueField DPU, and elevated privileges to probe device support. It addresses the most common failure: the exporter sends a config with a counter name, but the device does not actually expose that counter, so the metric drops silently. Before you commit a config, run doca_telemetry_utils <pci_address> <counter_name> <properties> to confirm it does not report “not supported”.

This is the operator-side tool for testing a telemetry config. For exporter development, see doca-telemetry-exporter; for collector development, see doca-telemetry; for DOCA Telemetry Service deployment, see doca-dts.

What it helps with

  • find out which diagnostic counters this BlueField actually exposes
  • convert a counter name to its binary Data ID before sending to the collector
  • figure out why the exporter config ships but the collector sees nothing
  • validate that a device supports a specific counter with given properties
  • decode a Data ID from logs back to counter name and properties

Example prompts for the agent

  • What counters are available on our BlueField? Run doca_telemetry_utils get-counters and show me the list.
  • I see Data ID: 0x1160000600030201 in the logs — translate it back to the counter name and its properties.
  • Check if the BlueField at PCI address 0000:08:00.0 supports the port_rx_bytes counter before I add it to the exporter config.

How to install doca-telemetry-utils

1Skills CLI (Vercel)

npx skills add NVIDIA/skills --skill doca-telemetry-utils -a claude-code

2Manually: put the files in place

~/.claude/skills/doca-telemetry-utils/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/doca-telemetry-utils/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about doca-telemetry-utils

How do I install doca-telemetry-utils for Claude Code?

Run npx skills add NVIDIA/skills --skill doca-telemetry-utils -a claude-code, then open ~/.claude/skills/doca-telemetry-utils/SKILL.md.

What does doca-telemetry-utils do?

It invokes the CLI utility on a host with DOCA to enumerate available counters, translate names to Data IDs and back, and validate that a device supports a counter before you commit the exporter config.

What do I need for doca-telemetry-utils to work?

DOCA SDK installed in /opt/mellanox/doca with the Telemetry component, a visible BlueField DPU at a known PCI address, and elevated privileges to probe device support.

Source text

SKILL.md · Apache-2.0
---
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 <[email protected]>
  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 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.

© NVIDIA · Apache-2.0 · NVIDIA/skills

Similar skills

All skills for DevOps and infrastructure →

From the same set312

The whole set →
i4h-workflow-train-rl i4h-workflow-train-rl is a Claude Code skill for training, evaluating, and exporting RL policies for Workflow with RSL-RL or RLinf profiles. CX Codex +1 ★ 4,106repo stars doca-pipeline-language-developer-tools doca-pipeline-language-developer-tools routes an agent through the DOCA Pipeline Language debugging toolset on a BlueField DPU: DPL Nspect, DPL Debugger, DPL Admin, P4 Runtime Shell and the DPL Runtime Controller SDK. CX Codex +1 ★ 4,106repo stars runai-diagnose-failed-workload runai-diagnose-failed-workload diagnoses crashed, stopped, OOMKilled, and startup-failed Run:ai workloads using structured evidence and read-only cluster queries. CX Codex +1 ★ 4,106repo stars doca-upgrade The doca-upgrade skill checks the installed DOCA release, reports the gap to a target, and waits for explicit approval before guiding a change. It also covers rollbacks and interrupted upgrades. CX Codex +1 ★ 4,106repo stars doca-socket-relay Bridges host socket traffic onto a BlueField DPU via DOCA Socket Relay without rewriting applications. CX Codex +1 ★ 4,106repo stars nvshmem-troubleshoot-and-report-bugs nvshmem-troubleshoot-and-report-bugs uses launch details and per-PE logs to investigate NVSHMEM runtime failures and draft a bug report. Its diagnosis workflow is read-only. CX Codex +1 ★ 4,106repo stars doca-dpdk-bridge The doca-dpdk-bridge skill adds DOCA Flow and other DOCA features to an existing DPDK application, binding ports and converting buffers between DPDK and DOCA without rewriting the fastpath. CX Codex +1 ★ 4,106repo stars doca-dts doca-dts is a Claude Code skill that deploys and configures NVIDIA DOCA Telemetry Service on BlueField DPUs, Docker hosts, and DPF clusters. It covers DTS setup across these environments. CX Codex +1 ★ 4,106repo stars

Project sponsors

Companies that keep this analytics open