About this skill
---
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
version?"*. Answered by the version-overlay in
[`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility),
which redirects to the canonical
[`doca-version`](../../doca-version/SKILL.md) 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`](../../libs/doca-telemetry/SKILL.md),
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](../../libs/doca-telemetry-exporter/SKILL.md)
when present, or via
[`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md)).
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-public-knowledge-map/SKILL.md),
[`doca-telemetry`](../../libs/doca-telemetry/SKILL.md),
or [`doca-setup`](../../doca-setup/SKILL.md).
## 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 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`](../../libs/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`](../../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`](../../libs/doca-telemetry/SKILL.md).
## Loading order
1. Read this `SKILL.md` 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 [CAPABILITIES.md](CAPABILITIES.md).**
3. **For the documented invocations and the
discover → resolve → validate → consume
workflow — `install`, `configure`, `build`,
`modify`, `run`, `test`, `debug`, `use` — see
[TASKS.md](TASKS.md).**
## Related skills
- [`doca-telemetry`](../../libs/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`](../../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`](../../doca-version/SKILL.md) —
canonical DOCA version-handling rules. The
`## Version compatibility` section in
[`CAPABILITIES.md`](CAPABILITIES.md) is a concise
overlay that redirects here for the body and
adds the *tool ↔ `doca-telemetry` library
schema-version pairing* rule.
- [`doca-setup`](../../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`](../../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`](../../doca-structured-tools-contract/SKILL.md)
— the bundle's detect → prefer → fall back →
report contract for structured helper tools. The
command appendix in [`TASKS.md`](TASKS.md)
honors this contract.
- [`doca-programming-guide`](../../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.