doca-telemetry-utils — скилл для Claude Code
Скилл для Claude Code и Codex, который запускает doca_telemetry_utils на хосте с DOCA и помогает отследить, куда исчезают метрики телеметрии между экспортером и коллектором.
Apache-2.0 ★ 4 106 обновлён 2026-10-23
npx skills add NVIDIA/skills --skill doca-telemetry-utils -a claude-codeЧто делает doca-telemetry-utils
Скилл вызывает командную строку doca_telemetry_utils и помогает решить три задачи: перечислить доступные диагностические счётчики для BlueField, перевести имя счётчика в его Data ID (и обратно по ID из логов), проверить, поддерживает ли конкретное устройство нужный счётчик с заданными свойствами.
Нужна установленная DOCA SDK на Linux (Ubuntu 22.04, 24.04 или RHEL/SLES) с компонентом Telemetry в /opt/mellanox/doca, видимый BlueField DPU и повышенные привилегии для проверки поддержки на устройстве. Скилл парирует самую частую ошибку: экспортер отправляет конфиг с именем счётчика, но устройство этот счётчик не поддерживает, и метрика молча падает. Перед тем как сохранить конфиг, проверь, что doca_telemetry_utils <адрес_PCI> <имя_счётчика> <свойства> не выдаст «not supported».
Это оператор-сторонний инструмент для тестирования конфига телеметрии; для разработки экспортера обращайся к doca-telemetry-exporter, для разработки коллектора — к doca-telemetry, для развёртывания DOCA Telemetry Service — к doca-dts.
Какие задачи решает
- найти, какие диагностические счётчики BlueField поддерживает на самом деле
- перевести имя счётчика в его бинарный Data ID перед отправкой в коллектор
- разобраться, почему экспортер отправляет конфиг, но коллектор ничего не видит
- проверить, поддерживает ли устройство конкретный счётчик с нужными свойствами
- расшифровать Data ID из логов обратно в имя и свойства счётчика
Примеры запросов агенту
- Какие счётчики доступны на нашем BlueField? Запусти
doca_telemetry_utils get-countersи покажи список. - Я вижу в логе
Data ID: 0x1160000600030201— переведи обратно в имя счётчика и его свойства. - Проверь, поддерживает ли BlueField на PCI адресе
0000:08:00.0счётчикport_rx_bytesперед тем, как я добавлю его в конфиг экспортера.
Как установить doca-telemetry-utils
1Через Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-telemetry-utils -a claude-code2Вручную: положить файлы
~/.claude/skills/doca-telemetry-utils/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/doca-telemetry-utils/
1Через Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-telemetry-utils -a codex2Вручную: положить файлы
.agents/skills/doca-telemetry-utils/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-telemetry-utils -a cursor2Вручную: положить файлы
.cursor/skills/doca-telemetry-utils/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install NVIDIA/skills skills/doca-telemetry-utils2Вручную: положить файлы
.github/skills/doca-telemetry-utils/SKILL.md1Через Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-telemetry-utils -a gemini-cli2Командой платформы
gemini skills install https://github.com/NVIDIA/skills --path skills/doca-telemetry-utilsВручную: положить файлы
.devin/skills/doca-telemetry-utils/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Claude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о doca-telemetry-utils
Как установить doca-telemetry-utils в Claude Code?
Запусти npx skills add NVIDIA/skills --skill doca-telemetry-utils -a claude-code, затем открой ~/.claude/skills/doca-telemetry-utils/SKILL.md.
Что делает doca-telemetry-utils?
Вызывает CLI-утилиту на хосте с DOCA, чтобы перечислить доступные счётчики, переводить имена в Data ID и обратно, проверять поддержку счётчика на конкретном устройстве перед тем, как сохранить конфиг экспортера.
Что нужно для работы doca-telemetry-utils?
DOCA SDK, установленная в /opt/mellanox/doca с компонентом Telemetry, видимый BlueField DPU на известном PCI-адресе и повышенные привилегии для проверки поддержки на устройстве.
Исходный текст
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