/doca-telemetry

license: Apache-2.0
name: doca-telemetry
description: >
  Use this skill to read DOCA hardware-counter events from a `doca_dev`
  through the per-domain Telemetry reader libraries:
  `doca_telemetry_pcc`, `_dpa`, `_diag`, `_adp_retx`, `_phy`, and
  `_pci`. It covers capability checks, context creation, startup, and
  per-domain reads or samples. Trigger for implicit requests such as
  "read PCC counters from my BlueField app", "sample DPA counter
  exports", or "expose PHY, PCI, or DIAG counters from this doca_dev".
  This is the counter-reader surface, not a NetFlow, IPFIX, or
  local-socket collector. Route publishing and export to
  `doca-telemetry-exporter`; route the deployed DOCA Telemetry Service
  to `doca-dts`, and collectors and plain stdout logging elsewhere.
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - telemetry
    - counters
compatibility: >
  Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu
  22.04/24.04 or RHEL/SLES) with a BlueField DPU or ConnectX NIC
  attached. Reads the user's local install via `pkg-config
  doca-telemetry` and inspects
  /opt/mellanox/doca/{lib,include,samples,applications}. The validation
  steps require a live DOCA install.

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 Conges