---

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 if the user wants to do something (configure / build / modify + rebuild / run / test / debug); open 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 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 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 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 object table + the workflow in TASKS.md ## configure + 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 (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.
• "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 (the source was never started, or an OTLP context is missing on write/flush) + the lifecycle order in 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
  • the file-write smoke and check_ipc_status steps in 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 (cross-linking the detection chain in doca-version) plus the honest introspection rule in 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).

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 → 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 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 (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 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 → 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), or non-exporter library questions. For those, use doca-public-knowledge-map.

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 → _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 — 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 *