doca-telemetry-utils

Files (8)

• BENCHMARK.md
• CAPABILITIES.md
• SKILL.md
• SKILLCARD.yaml
• TASKS.md
• evals.json · evals/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

# 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.

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills