/doca-telemetry-exporter

DOCA Telemetry Exporter capabilities, publish surfaces, version overlay, errors, observability, safety

Where to start: Pick the H2 anchor that matches your question (role-split / object family / publish-surface selection / version / errors / observability / safety) and read that section end-to-end. The tables in each section are the load-bearing content; the prose around them is interpretation.

Read this file when the loader sent you here from SKILL.md. For the how of executing each pattern (the verbs configure / build / modify / run / test / debug), jump to TASKS.md. For the canonical DOCA version-handling rules that this skill layers an exporter overlay on top of, see doca-version.

Ground-truth note. Every symbol, macro, error code, default path, and lifecycle step in this file is quoted from the public exporter headers (doca_telemetry_exporter.h, doca_telemetry_exporter_netflow.h) and the shipped samples under /opt/mellanox/doca/samples/doca_telemetry_exporter/. The headers-win-over-docs rule (doca-version) applies: if the installed header disagrees with anything here, the header is authoritative and the agent must re-read it before answering.

Pattern overview

Every telemetry-exporter question this skill teaches resolves into one of SIX patterns. The patterns are CLASSES — they apply across every exporter release and every DOCA-using application, not just the worked examples shown.

Two cross-cutting rules that apply to every pattern above:

• The exporter is the publisher; the receiver is a separate artifact. doca-telemetry-exporter is what the user's application links to publish telemetry. The aggregating / collecting side (the DOCA Telemetry Service, DTS — reached over IPC) and any downstream OpenTelemetry Collector are separate, each with its own public guide reachable through doca-public-knowledge-map. Conflating the two is the #1 first-app confusion and the agent must surface the distinction before any code-level guidance.
• Delivery is buffered and flush-based, not a blocking submit. Reports accumulate in an internal buffer that is flushed when full or on an explicit doca_telemetry_exporter_source_flush() (or the Metrics API's _metrics_flush / auto flush interval). A _source_report does NOT block on a full transport and does NOT return DOCA_ERROR_AGAIN — there is no such return in this API. The NetFlow _netflow_send reports how many records it actually sent via its records_sent out-parameter; a short send is the backpressure signal on that surface.

Capabilities and modes

DOCA Telemetry Exporter is a CollectX-backed publisher library, not a DOCA Core Context. It does NOT use the doca_ctx_create → doca_ctx_start lifecycle and there is no doca_ctx handle for the exporter. The lifecycle is instead a schema → source progression, with three optional per-source publish contexts (metrics / OTLP logs) and one sibling top-level API (NetFlow).

Role split — exporter (publisher) vs telemetry service (receiver). The exporter is asymmetric and the asymmetry is the #1 first-app confusion.

Object family. The public surface is closed; the agent must not invent additional object types or a doca_ctx.

Publish surfaces. ONE source can drive several publish surfaces. The agent MUST pick the surface that matches intent before writing any report call.

Export destinations (transports). Enabled on the schema (or via the NetFlow API / env var) BEFORE start. Multiple may be enabled at once.

Capability discovery — the honest rule. Unlike accelerator libraries (SHA, RDMA, Compress, Flow), DOCA Telemetry Exporter has no doca_devinfo capability-query family and no doca_caps data — the doca_caps telemetry-exporter dump is a stub that returns success with no fields. Do NOT tell the user to run a doca_telemetry_exporter_*_get_* "cap query" for max fields / max event size / supported event types; those functions do not exist. The only runtime introspection the library offers is:

• doca_telemetry_exporter_check_ipc_status(source, &status) — is the IPC transport CONNECTED / FAILED / DISABLED.
• doca_telemetry_exporter_source_get_opaque_report_max_data_size(source, &max) — the max opaque payload size for this source.
• the doca_telemetry_exporter_schema_get_* config getters — read back the buffer / file-write / IPC settings you set.

Everything else is validated the sample-driven way: enable file write, run, and inspect the emitted binary data files (and/or confirm receipt at the DTS / collector). See ## Observability.

Version compatibility

For the canonical DOCA version-detection chain, the four-way match rule, NGC container semantics, and the headers-win-over-docs rule, see doca-version. The body lives there; this skill does not duplicate it.

The exporter-specific overlay is:

• Use pkg-config --modversion doca-telemetry-exporter as the build-time anchor. Per doca-version TASKS.md ## configure, this MUST match the other version sources. Because there is no doca_caps data for this library, the four-way match's doca_caps --version leg is a whole-install version check, NOT a per-artifact capability probe for the exporter.
• The Metrics API, OTLP-logs API, typed-_source_report, and _schema_set_indexes / _get_indexes are DOCA_EXPERIMENTAL. They require building with -DDOCA_ALLOW_EXPERIMENTAL_API (per doca-programming-guide); they may change across releases. The DOCA_STABLE surface includes the schema → source core (schema_init / schema_start / source_create / source_start / source_destroy / schema_destroy), typed-schema registration (type_create / field_create / type_add_field / schema_add_type), source_opaque_report / source_flush / check_ipc_status / get_timestamp, the full schema_set_* / schema_get_* config family, and the entire NetFlow sibling API in doca_telemetry_exporter_netflow.h. Confirm the DOCA_STABLE / DOCA_EXPERIMENTAL marker in the installed header before relying on any symbol — the shipped samples still set -DDOCA_ALLOW_EXPERIMENTAL_API blanket-style even when only stable symbols are used.
• The exporter is distinct from the DOCA Telemetry Service across every release. When the user reports "the docs I'm reading talk about a telemetry SERVICE — is that this library?", the answer is no. Route to doca-public-knowledge-map for the service guide.
• doca-telemetry-exporter.pc plus doca-common.pc must both match doca_caps --version at the version check (per doca-version CAPABILITIES.md ## Version compatibility). A common partial-install pattern after a DOCA upgrade is that doca-telemetry-exporter.pc lingers from the previous release while doca-common.pc was refreshed; route to doca-version TASKS.md ## debug ladder step 2 before any exporter-layer diagnosis.

Error taxonomy

Only the doca_error_t codes the exporter headers actually document appear below. There is no DOCA_ERROR_AGAIN (delivery is buffered/flush-based, not a blocking submit) and no DOCA_ERROR_NOT_FOUND on this API surface — do not invent them. The cross-library taxonomy lives in doca-programming-guide CAPABILITIES.md ## Error taxonomy; the rows below are the exporter surface meanings.

The agent's rule: identify which row above is the cause before recommending any change; never invent an AGAIN/NOT_FOUND retry loop. A BAD_STATE wants the lifecycle fixed; an INVALID_VALUE wants the type/field/label definition fixed.

Observability

The exporter's observability is per-call return + IPC status + the emitted data itself + the receiver side. There is no progress-engine completion stream (this is not a Core context).

Four primary signals the agent should reach for:

1. Per-call return. Every doca_telemetry_exporter_* call returns a doca_error_t; inspect it. For NetFlow, ALSO inspect the records_sent out-parameter of _netflow_send — records_sent < count is a partial send (backpressure at the collector / transport), which the NetFlow sample treats as a failure.
2. IPC status. doca_telemetry_exporter_check_ipc_status returns DOCA_TELEMETRY_EXPORTER_IPC_STATUS_CONNECTED / _FAILED / _DISABLED. When IPC is enabled but the DTS is not up, this is where the agent sees it — BEFORE blaming the report calls.
3. File-write inspection (the cheapest end-to-end check). Enable _schema_set_file_write_enabled, run, and inspect the binary data files under the data root. The shipped samples themselves rely on this as the "did it work" signal. A file with the expected schema + rows is the green signal for the publish half of the contract.
4. Receiver-side reception (true end-to-end). For IPC → DTS, OTLP → OpenTelemetry Collector, or NetFlow → collector, the true signal is that the receiver logged / stored the events. An exporter returning success on every call while the receiver is empty is the canonical "published into a transport with no reader" failure — route via the receiver's own guide reached through doca-public-knowledge-map.

For the cross-cutting observability primitives (DOCA_LOG_LEVEL, the doca-<lib>-trace build flavor) see doca-debug CAPABILITIES.md ## Observability. For the install-tree layout defer to doca-public-knowledge-map.

Safety policy

Overlay on the bundle-wide hardware-safety meta-policy. The rules below are this skill's per-artifact overlay on the cross-cutting rules in doca-hardware-safety CAPABILITIES.md ## Safety policy. Telemetry publishing does not change hardware or fabric state (no mlxconfig, no firmware, no eswitch/representor change), so the hardware-safety triggers do not fire here. The safety surface is transport staging + destination permissions + buffer-flush semantics.

The staging + permission matrix the agent must walk for any new exporter setup:

• No sudo as a rule. The exporter runs in the application's own process as the application's user. If the first reaction to an init failure is to add sudo, walk it back: the cause is almost always an unwritable data root or a receiver that is not up, not a missing privilege on the exporter process.
• Delivery never blocks the data path. Because reporting is buffered and flush-based (not a blocking submit), there is no hot-path back-pressure knob and no DOCA_ERROR_AGAIN to handle. If loss under load matters, tune buffer size (_schema_set_buf_size) and flush cadence, or widen the receiver — do NOT invent a retry loop.
• Validate with a file-write smoke before any bulk / IPC run. Enabling file write and inspecting the emitted data files is the cheapest way to prove the schema/type/report path is correct independent of any receiver. The loop is in TASKS.md ## test.

Deferred topic boundaries

This skill scopes itself to the DOCA Telemetry Exporter library. Adjacent topics the agent will get asked but should route elsewhere:

• The DOCA Telemetry Service (DTS, the receiver) — separate DOCA service with its own public guide. Reach via doca-public-knowledge-map. This skill is publisher-side only.
• CollectX (clx) collection deployment — the collector-side deployment lives in doca-collectx-deployment.
• Downstream rendering / dashboards — once events reach the receiver, the downstream sinks (NetFlow / IPFIX / Prometheus / Grafana / OpenTelemetry Collector) are governed by their own ecosystems and guides.
• DOCA Core context and progress-engine internals — owned by doca-programming-guide. Note the exporter is NOT a Core context; do not apply the doca_ctx lifecycle to it.
• Real-time event subscription back into the app — the exporter is publish-only / one-way. The right primitive is doca-comch for a bi-directional message channel, not the exporter.
• Plain structured logging to stdout / files — use doca_log (documented in doca-programming-guide).
• Cross-cutting DOCA_ERROR_* taxonomy — owned by doca-programming-guide CAPABILITIES.md ## Error taxonomy.
• Cross-cutting debug ladder — owned by doca-debug ## debug. This skill's ## debug overlays the runtime + program layers.