doca-telemetry

Files (9)

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

SKILL.md (first lines)

# DOCA Telemetry

## Examples

- **"Build a second program that RECEIVES the events my exporter app
  publishes."** No DOCA library consumes exporter events, and this skill
  is not that library: `doca-telemetry` reads a device's hardware
  counters. The app links `doca-telemetry-exporter` to publish; the
  receiver is the DOCA Telemetry Service over IPC (`doca-dts`), or the
  exporter's file output for a local smoke. Do not invent a consume or
  collector API. Then: the publishing app owns the schema; check the IPC
  path with `doca_telemetry_exporter_check_ipc_status`; smoke one event
  with field values intact (file output) before bulk; when reporting
  cannot keep up, drop or aggregate on the hot path, never block.

- **"Read PCC counters from my BlueField app."** — this is in
  scope. Use the per-domain Telemetry reader; do not stand up
  DTS or an exporter here. Sequence: `doca_telemetry_pcc_cap_is_supported`
  on the device, create the PCC context on the open `doca_dev`
  (`doca_telemetry_pcc_rep_create` for a representor), start it, read
  once with `doca_telemetry_pcc_get_counters`, then stop and destroy.
  Reads before start return `DOCA_ERROR_BAD_STATE`.
- **"Sample DPA counter exports."** — stay on
  `doca_telemetry_dpa` reads. Publishing those samples belongs
  to the exporter skill.

## Instructions

Follow Loading order below. Open the tasks companion for configure /
read / debug. Open the capabilities companion for the per-domain
readers. Do not open every companion file.

**Where to start:** This skill assumes DOCA is already installed
and the user is doing **hands-on hardware-counter-reader work** —
opening a per-domain `doca_telemetry_<domain>` context against a
`doca_dev` and reading the latest hardware-counter snapshot for
that domain. The library is the **counter-READER** half of DOCA
telemetry; it is NOT a NetFlow / IPFIX collector and NOT a
generic schema-event consumer (there is no NetFlow / IPFIX /
local-socket transport surface in the public header).
Open the tasks companion if the user wants to *do* something
(configure / build / modify / run / test / debug); open
the capabilities companion when the question is *which
hardware-counter domains can this device read* on this install
(PCC, DPA, DIAG, ADP_RETX, PHY, PCI). If the user has not
installed DOCA yet, route to
`doca-setup/SKILL.md` first. If the user is
confused about whether they want this library (HW-counter
reader on a `doca_dev`) or
`doca-telemetry-exporter/SKILL.md`
(the publisher / export side, which is a separate library and
publishes structured telemetry / labeled metrics / OTLP logs),
read the reader-vs-exporter role split in
the capabilities companion
BEFORE configuring anything; mixing the two is the load-bearing
first-app failure for this skill. If the user is asking about
**DOCA Telemetry Service (DTS) as deployed**, route to `doca-dts`.

## Audience

This skill serves **external developers building applications
that READ DOCA hardware counters from a `doca_dev` through one
or more of the six per-domain DOCA Telemetry reader libraries**
(`doca_telemetry_pcc` / `_dpa` / `_diag` / `_adp_retx` / `_phy` /
`_pci`) — i.e., users whose application code calls
`doca_telemetry_<domain>_*` (directly in C/C++, or through FFI /
bindings from another language) to open a per-domain context on
a `doca_dev`, configure the per-domain sample window, and read
the hardware-counter snapshot for that domain. It is *not* for
NVIDIA developers contributing to DOCA Telemetry itself, and it
is *not* for users writing the **publishing / export** side —
that is
`doca-telemetry-exporter/SKILL.md`,
a separate library and a separate skill.

**Language scope.** DOCA Telemetry's per-domain reader libraries
ship as a C surface with `pkg-config` module name
`doca-telemetry`. The shipped samples are written in C. C and
C++ readers are the canonical case; the worked examples in
the tasks companion assume that path. Other-language readers (Rust, Go,
Python, …) consume the same `*.so` through FFI or
language-specific bindings; the skill's contribution in that
case is to keep the reader-vs-exporter distinction, the per-
domain cap-query-first discipline, the per-domain DOCA Core
lifecycle on the `doca_dev`, the sample-window discipline, and
the error-taxonomy guidance language-neutral, and to route the
agent to the public per-domain C ABI as the authoritative
surface that any wrapper will eventually call.

## When to load this skill

Load this skill when the user is doing hands-on DOCA Telemetry
**hardware-counter-reader** work, in any language. Concretely:

- Picking the right per-domain header for the counters the user
  wants (`doca_telemetry_pcc.h` for Programmable Congestion
  Control counters, `_dpa.h` for DPA counters, `_diag.h` for
  generic device diagnostic counters, `_adp_retx.h` for ADP
  retransmit counters, `_phy.h` for physical-layer counters,
  `_pci.h` for PCI / PCIe counters) and confirming the device
  supports it via the per-domain `_cap_is_supported(devinfo)`
  query — **except `_pci`, which has no single `_cap_is_supported`
  and instead exposes per-feature caps like
  `doca_telemetry_pci_cap_management_info_is_supported` /
  `_cap_perf_counters_1_is_supported`.**
- Opening a per-domain `doca_telemetry_<domain>` context on a
  `doca_dev`, walking the per-domain lifecycle
  (`doca_telemetry_<domain>_create(dev)` → per-domain setters →
  `doca_telemetry_<domain>_start`), configuring the per-domain
  sample window, and reading the hardware-counter snapshot for
  that domain. Note this is a per-domain `_create`/`_start`
  surface, not the generic `doca_ctx_*` progress-engine
  lifecycle.
- Reading the device + library capability surface before assuming
  a counter family is available: use
  `doca_telemetry_<domain>_cap_is_supported` only for `pcc`,
  `dpa`, `diag`, `adp_retx`, and `phy`; use the matching
  per-feature `doca_telemetry_pci_cap_*_is_supported` query for
  PCI.

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills