/doca-telemetry-exporter

license: Apache-2.0
name: doca-telemetry-exporter
description: >
  Use this skill when the user is doing hands-on DOCA Telemetry Exporter
  programming on a host where DOCA is installed — defining a
  doca_telemetry_exporter_schema and event types, creating sources,
  picking a publish surface (typed events / opaque events / the metrics
  counter-gauge-histogram API / OTLP logs / NetFlow), walking the
  schema-then-source lifecycle, or debugging DOCA_ERROR_* failures from
  the exporter API. Trigger even when the user does not explicitly
  mention "DOCA Telemetry Exporter" or "doca_telemetry_exporter_*" —
  typical implicit phrasings include "publishing counters from my DOCA
  app", "BAD_STATE when I report an event", "consumer/DTS sees nothing
  but my report succeeded", "how do I export NetFlow/IPFIX records", or
  "should I link the exporter or the telemetry service". Refuse and
  route elsewhere for the receiving DOCA Telemetry Service (DTS), plain
  stdout logging via doca_log, or real-time event subscription back into
  the app via doca-comch — those belong to other skills.
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - telemetry
    - exporter
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-exporter` and inspects
  /opt/mellanox/doca/{lib,include,samples,applications}. The validation
  steps require a live DOCA install.

DOCA Telemetry Exporter

Examples

• **"Publishing counters from my DOCA app."** — this is in

scope. Walk schema-then-source; do not configure DTS here.

• **"BAD_STATE when I report an event."** — check the lifecycle

order before changing the report call.

Instructions

Follow Loading order below. Open the tasks companion for configure / publish / debug. Open the capabilities companion for publish surfaces. Do not open every companion file.

**Where to start:** This skill assumes DOCA is already installed and the user is doing **hands-on telemetry-exporter work** — emitting structured application telemetry (counters / events) from a DOCA-using program to an external consumer. Open the tasks companion if the user wants to *do* something (configure / build / modify + rebuild / run / test / debug); open the capabilities companion when the question is *what can the exporter express* on this install. 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 or the DOCA Telemetry Service (the receiver) — read the exporter-vs-service rule in the capabilities companion before configuring anything.

> **This library is NOT a DOCA Core context.** There is no > `doca_ctx_start()` for the exporter and no per-`doca_devinfo` > capability-query family (its `doca_caps` dump is a stub). The > lifecycle is `schema_init` → configure exporters → register > type(s) → `schema_start` → `source_create` → `source_start` → > report → flush → destroy.

Example questions this skill answers well

The CLASSES of telemetry-exporter questions this skill is built to answer, each with one worked example. The agent should treat the *class* as the load-bearing piece — the worked example is a single instance.

• **"Which library do I want — the exporter or the telemetry

service?"** — worked example: *"I want my DOCA Flow program to publish a per-second packets-processed counter to a downstream collector — which DOCA artifact do I link?"*. Answered by the exporter-vs-service rule in

Capabilities and modes

role-split table + the path-selection bullet, both of which name `doca-telemetry-exporter` as the publisher the application links and route the receiving / consuming side away from this skill.

• **"How do I emit my first structured event from a DOCA program?"** —

worked example: *"emit a `packets_processed` event record from my DOCA Flow application"*. Answered by the schema → source lifecycle in

Capabilities and modes

object table + the workflow in

configure +

run step 3 (file-write smoke before

bulk), starting from the `telemetry_export/` sample.

• **"Which publish surface do I want — typed events, metrics, OTLP

logs, or NetFlow?"** — worked example: *"I want labeled per-interface packet counters and a bandwidth gauge"*. Answered by the publish-surface table in

Capabilities and modes

(that intent maps to the Metrics API — `_metrics_add_counter` / `_add_gauge` — and the `telemetry_export_metrics/` sample), plus the sample map in ## modify.

• **"My report call returns `DOCA_ERROR_BAD_STATE` — what did I

get wrong?"** — worked example: *"`doca_telemetry_exporter_source_report` returns `BAD_STATE` on the first call"*. Answered by the `BAD_STATE` row in

Error taxonomy

(the source was never started, or an OTLP context is missing on write/flush) + the lifecycle order in

configure. Note there is NO

`DOCA_ERROR_AGAIN` and NO `DOCA_ERROR_NOT_FOUND` on this API.

• **"My program reports, but the DTS / collector sees nothing —

where do I start?"** — worked example: *"my report returns success, but the DTS log is empty"*. Answered by the receiver-up-first staging in

Safety policy

• the file-write smoke and `check_ipc_status` steps in

test (prove the publish half with

file write, then confirm IPC is `CONNECTED` and the receiver is up).

• **"How do I confirm the exporter is installed and my transport

is live?"** — worked example: *"is the exporter on my DOCA 3.x install, and is IPC to DTS actually connected?"*. Answered by the version-compatibility overlay in

Version compatibility

(cross-linking the detection chain in `doca-version/SKILL.md`) plus the honest introspection rule in

Capabilities and modes

(`doca_telemetry_exporter_check_ipc_sta