doca-telemetry-exporter · diff
git:20260727.a5736e4 to git:20260805.36dd834
100 added, 85 removed. Audit A to A.
---
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, creating sources, picking
- counter/gauge/event types, running capability queries before
- assuming limits, registering schemas before the first emit, 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", "emit
- returns AGAIN under bulk load", "consumer sees nothing but emit
- reports success", "NOT_FOUND on first submit", or "should I link
- the exporter or the telemetry service". Refuse and route elsewhere
- for the receiving DOCA Telemetry Service, plain stdout logging via
- doca_log, non-DOCA Prometheus scrape sinks, or real-time event
- subscription back into the app via doca-comch — those belong to
- other skills.
+ 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 single per-second `packets_processed`
- counter event from my DOCA Flow application"*. Answered by the
- schema-register-before-emit lifecycle in
+ 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 (single-event smoke
- before bulk).
- - **"My event-emit call returns `DOCA_ERROR_AGAIN` under load —
- should I retry?"** — worked example: *"my high-rate emit loop
- starts returning `AGAIN` once the downstream consumer falls
- behind — do I sleep-and-retry?"*. Answered by the hot-path
- drop-not-block invariant in
- [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
- + the `AGAIN` row in
- [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy):
- the app's correct response is to drop the event (or buffer
- bounded) — never block the data path on telemetry.
- - **"My emit returns `DOCA_ERROR_NOT_FOUND` — what did I forget?"** —
- worked example: *"`doca_telemetry_exporter_source_report` returns
- `NOT_FOUND` on the very first call"*. Answered by the `NOT_FOUND`
- row in
+ [`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)
- (schema for the event type was never registered against this
- source) + the lifecycle order in
- [`TASKS.md ## configure`](TASKS.md#configure) (register schemas
- BEFORE the first emit).
- - **"My program emits, but the consumer sees nothing — where do I
- start?"** — worked example: *"emit returns success, but the
- collector log on the same host is empty"*. Answered by the
- consumer-must-be-up-first rule in
+ (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)
- permission matrix + the smoke-before-bulk loop in
- [`TASKS.md ## test`](TASKS.md#test) (one event end-to-end with
- consumer reception confirmed BEFORE any bulk emit).
- - **"Is `doca_telemetry_exporter_*` on my installed DOCA, and is
- the event type I want supported here?"** — worked example: *"is
- the gauge type on DOCA 3.3 against my install?"*. Answered by
+ + 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),
- which cross-links the canonical detection chain in
- [`doca-version`](../../doca-version/SKILL.md), plus the
- capability-query rule in
- [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes).
+ [`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`](CAPABILITIES.md#capabilities-and-modes)
+ (`doca_telemetry_exporter_check_ipc_status`, not a device
+ cap-query).
## Audience
This skill serves **external developers building applications that
emit structured telemetry through DOCA Telemetry Exporter** — i.e.,
users whose application code calls `doca_telemetry_exporter_*`
(directly in C/C++, or through FFI/bindings from another language)
to publish counters, gauges, and events from their DOCA-using
program to an external telemetry consumer. It is *not* for NVIDIA
developers contributing to DOCA Telemetry Exporter itself, and it
is *not* for users building the receiving / aggregating telemetry
service (the DOCA Telemetry Service is a separate DOCA service with
its own public guide, reached via
[`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md)).
**Language scope.** DOCA Telemetry Exporter ships as a C library
with `pkg-config` module name `doca-telemetry-exporter`. The
shipped samples are written in C. C and C++ consumers are the
canonical case; the worked examples in `TASKS.md` assume that path.
Other-language consumers (Rust, Go, Python, …) consume the same
`*.so` through FFI or language-specific bindings; the skill's
contribution in that case is to keep the exporter-vs-service
- distinction, the schema-register-before-emit lifecycle, the
- capability-discovery rule, the same-user-as-the-app permission
- rule, the hot-path drop-not-block invariant, and the error-taxonomy
+ distinction, the schema → source lifecycle, the transport-not-caps
+ discovery rule, the same-user-as-the-app permission rule, the
+ buffered flush-based delivery model, and the error-taxonomy
guidance language-neutral, and to route the agent to the public 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
Exporter work, in any language. Concretely:
- Defining a `doca_telemetry_exporter_schema` for the events the
application will emit (field names + field types), and
registering it with the exporter BEFORE any event is published.
- Creating one or more `doca_telemetry_exporter_source` instances
to represent distinct logical sources of telemetry inside the
application (e.g. one source per worker thread / per pipeline
stage).
- - Picking the right `doca_telemetry_exporter_type` (counter,
- gauge, event) for each field the application reports.
- - Reading the device + library capability surface for the
- exporter via the `doca_telemetry_exporter_*_get_*` query family
- before assuming a particular limit (max schema fields, max
- event size, …) is available on this install.
+ - Picking the right publish surface — typed structured events
+ (`_source_report`), opaque events (`_source_opaque_report`), the
+ Metrics API (counter / gauge / histogram), OTLP logs, or the
+ NetFlow sibling API — for what the application reports.
+ - Confirming the exporter's install + transport reality (there is
+ NO `doca_devinfo` cap-query family and NO `doca_caps` data for
+ this library): `doca_telemetry_exporter_check_ipc_status` for
+ IPC liveness, `_source_get_opaque_report_max_data_size` for the
+ opaque payload bound, and the `_schema_get_*` config getters.
- Debugging a `DOCA_ERROR_*` returned from an exporter call
- (lifecycle vs. invalid value vs. transport-queue-full vs.
- permission vs. transport / driver) and the per-emit status
- reported back to the application.
+ (`BAD_STATE` lifecycle-order vs. `INVALID_VALUE` type/label
+ mismatch vs. `NO_MEMORY` vs. `INITIALIZATION` vs. `UNKNOWN`
+ backend) and the per-call status returned to the application.
- Choosing between Telemetry Exporter and an adjacent option
(`doca_log` when stdout / structured-log shipping is enough; a
Prometheus client library when the user needs a non-DOCA-aware
sink; [`doca-comch`](../doca-comch/SKILL.md) when the user
needs a real-time event subscription back INTO the app — the
exporter is publish-only / one-way).
- Designing or extending non-C bindings (Rust, Go, Python, …)
that wrap the exporter C ABI — for the exporter-vs-service
- distinction, the schema-register-before-emit lifecycle, the
- permission policy, the hot-path drop-not-block invariant, and
- the capability + error rules the wrapper must honor.
+ distinction, the schema → source lifecycle, the permission
+ policy, the buffered flush-based delivery model, and the
+ transport-introspection + error rules the wrapper must honor.
Do **not** load this skill for general DOCA orientation, install
of DOCA itself, the receiving telemetry service (the DOCA
Telemetry Service has its own public guide reachable through
[`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md)),
or non-exporter library questions. For those, use
[`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md).
## What this skill provides
This is a **thin loader**. The body keeps only the orientation
needed to pick the right next file. The substantive
exporter-specific material lives in two companion files:
- `CAPABILITIES.md` — what the exporter can express on this
install: the exporter-vs-service role-split rule, the object
- family (`doca_telemetry_exporter_schema` → `_source` → `_type`
- with the schema-register-before-emit lifecycle), the
- capability-query surface (`doca_telemetry_exporter_*_get_*`),
- the exporter error taxonomy (mapped onto the cross-library
- `DOCA_ERROR_*` set, with the `AGAIN`-means-drop-not-block rule
- called out explicitly), the observability surface (per-emit
- status + capability snapshot at configure time + the consumer
- side as the end-to-end signal), the safety policy that gates
- the same-user-as-the-app permission and the
- consumer-must-be-up-first staging, and the path-selection rule
- against `doca_log`, Prometheus, and `doca-comch`.
+ family (`doca_telemetry_exporter_schema` → `_type`/`_field` →
+ `_source` with the schema → source lifecycle), the four publish
+ surfaces (typed events / opaque events / Metrics API / OTLP
+ logs) plus the NetFlow sibling API, the transport-not-caps
+ introspection rule (`check_ipc_status`,
+ `_get_opaque_report_max_data_size`, `_schema_get_*` — NO
+ `doca_caps` data, NO device cap-query), the exporter error
+ taxonomy (mapped onto the cross-library `DOCA_ERROR_*` set, with
+ the note that there is NO `AGAIN` and NO `NOT_FOUND` on this
+ surface), the observability surface (per-call status + IPC
+ status + file-write inspection + the receiver side as the
+ end-to-end signal), the safety policy that gates the
+ same-user-as-the-app permission and the receiver-up-first
+ staging, and the path-selection rule against `doca_log` and
+ `doca-comch`.
- `TASKS.md` — step-by-step workflows for the six in-scope
exporter verbs: `configure`, `build`, `modify` (followed by a
rebuild), `run`, `test`, `debug`. Plus a `Deferred task verbs` block that points
out-of-scope questions at the right next skill.
The skill assumes a host where DOCA is already installed at the
standard location, the application runs as a user that can write
to the telemetry transport the exporter is configured for, and a
receiving telemetry consumer is reachable and started before the
exporter. It does not cover installing DOCA — that path goes
through [`doca-setup`](../../doca-setup/SKILL.md) — and it does
not cover configuring / operating the receiving telemetry service,
which is a separate DOCA service with its own public guide.
## What this skill deliberately does not ship
This skill is **agent guidance**, not a samples or templates
bundle. To keep the boundary clean, it deliberately does not
contain — and pull requests should not add:
- **Pre-written DOCA Telemetry Exporter application source code,
in any language.** The verified exporter source code is the
shipped C samples at
`/opt/mellanox/doca/samples/doca_telemetry_exporter/`. The
agent's job is to route the user to those files and prescribe a
minimum-diff modification on them via the universal
modify-a-sample workflow in
[`doca-programming-guide`](../../doca-programming-guide/SKILL.md),
layered with the exporter-specific overrides in
[`TASKS.md ## modify`](TASKS.md#modify).
- **A telemetry consumer / collector / receiving service.** The
DOCA Telemetry Service is a separate DOCA service with its own
public guide; routing to it goes through
[`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md).
This skill is about the publisher side only.
- **Standalone build manifests** (`meson.build`, `CMakeLists.txt`,
`Cargo.toml`, …) parked inside the skill. The agent constructs
the build manifest *in the user's project directory* against
the user's installed DOCA, where `pkg-config --modversion
doca-telemetry-exporter` is the source of truth.
- **A `samples/`, `bindings/`, or `reference/` subtree** of any
kind. A mock or incomplete artifact in this skill's tree, even
one labeled "reference", is misleading: users will read it as
buildable.
## Loading order
1. Read this `SKILL.md` first to confirm the user's question is
in scope.
2. **For the exporter-vs-service rule, the object family, the
- schema-register-before-emit lifecycle, the capability-query
- surface, the error taxonomy (including the `AGAIN`-means-drop
- rule), observability, the safety policy, and the
- path-selection rule against `doca_log` / Prometheus / comch,
+ schema → source lifecycle, the four publish surfaces + NetFlow,
+ the transport-not-caps introspection rule, the error taxonomy
+ (note: no `AGAIN`, no `NOT_FOUND`), observability, the safety
+ policy, and the path-selection rule against `doca_log` / comch,
see [CAPABILITIES.md](CAPABILITIES.md).**
3. **For step-by-step workflows — configure, build, modify,
rebuild, run, test, debug — see [TASKS.md](TASKS.md).**
Both companion files cross-link to each other,
[`doca-version`](../../doca-version/SKILL.md) for the canonical
version-handling rules, and
[`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md)
whenever the right answer is "look it up in the public docs or
the installed package layout" rather than "exporter-specific
guidance".
## Related skills
- [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md) —
the routing table for every public DOCA documentation source
and the on-disk layout of an installed DOCA package. The
exporter's public guide URL is
`https://docs.nvidia.com/doca/sdk/DOCA-Telemetry-Exporter/index.html`;
the on-disk samples live under
`/opt/mellanox/doca/samples/doca_telemetry_exporter/`. The
DOCA Telemetry Service (the *receiver*, out of scope here) is
a separate guide reachable through that same routing table.
- [`doca-setup`](../../doca-setup/SKILL.md) — env preparation,
install verification, transport-side reachability checks, and
the *I have no install yet* path with the public NGC DOCA
container. This skill assumes its preconditions are satisfied
(in particular, the application user can write to the
telemetry transport).
- [`doca-version`](../../doca-version/SKILL.md) — canonical DOCA
version-handling rules. This skill's `## Version compatibility`
cross-links the four-way match rule + detection chain and adds
the exporter-specific overlay rules.
- [`doca-structured-tools-contract`](../../doca-structured-tools-contract/SKILL.md) —
the bundle's structured-tools precedence rule (detect / prefer
/ fall back / report). The Command appendix in
[TASKS.md](TASKS.md) honors this contract.
- [`doca-programming-guide`](../../doca-programming-guide/SKILL.md) —
general DOCA programming patterns shared by every library: the
canonical `pkg-config` + meson build pattern, the universal
modify-a-shipped-sample first-app workflow, the universal
lifecycle, the cross-library `DOCA_ERROR_*` taxonomy, and the
program-side debug order. This skill layers exporter specifics
on top.
- [`doca-comch`](../doca-comch/SKILL.md) — the right primitive
when the user needs a real-time event subscription back INTO
the application (host ↔ DPU control-plane messaging). The
exporter is publish-only / one-way; this skill's
path-selection rule routes there when subscription is the
actual requirement.
- [`doca-debug`](../../doca-debug/SKILL.md) — the cross-cutting
debug ladder (install / version / build / link / runtime /
- program / driver). Exporter-specific debug (consumer not up,
- schema-not-registered, transport queue full, hot-path block)
- overlays on top of that ladder.
+ program / driver). Exporter-specific debug (receiver not up,
+ lifecycle-order `BAD_STATE`, type/label `INVALID_VALUE`,
+ opaque-path-not-enabled) overlays on top of that ladder.