/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:
  kind: library
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}.

DOCA Telemetry Exporter

**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 [`TASKS.md`](TASKS.md) if the user wants to *do* something (configure / build / modify + rebuild / run / test / debug); open [`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what can the exporter express* on this install. If the user has not installed DOCA yet, route to [`doca-setup`](../../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 [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) 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.md ## Capabilities and modes`](CAPABILITIES.md#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.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) object table + the workflow in [`TASKS.md ## configure`](TASKS.md#configure) + [`TASKS.md ## run`](TASKS.md#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.md ## Capabilities and modes`](CAPABILITIES.md#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 [`TASKS.md ## modify`](TASKS.md#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 [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy) (the source was never started, or an OTLP context is missing on write/flush) + the lifecycle order in [`TASKS.md ## configure`](TASKS.md#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 [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)

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

[`TASKS.md ## test`](TASKS.md#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 [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility) (cross-linking the detection chain in [`doca-version`](../../doca-version/SKILL.md)) plus the honest introspection rule in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIE