Doca Telemetry

DOCA Telemetry capabilities, version overlay, errors, observability, safety

Where to start: Pick the H2 anchor that matches your question (reader-vs-exporter split / per-domain sub-libraries / per-domain lifecycle / capability discovery / path 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.

This library is the per-domain hardware-counter READER half of DOCA telemetry. It is not a NetFlow / IPFIX / local-socket collector framework, and there is no schema-registration / event-transport / publisher-consumer surface in the public header. Each domain ships its own small doca_telemetry_<domain>_* C API: a capability query on a doca_devinfo, a context created on a doca_dev, a per-domain _start, per-domain read / sample calls, then _stop / _destroy. The publishing / export side is the sibling doca-telemetry-exporter/SKILL.md library — a separate skill.

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 a per-domain overlay on top of, see doca-version/SKILL.md.

Pattern overview

Every hardware-counter-reader question this skill teaches resolves into one of SIX patterns. The patterns are CLASSES — they apply across every DOCA release and every per-domain reader sub-library, not just the worked examples shown.

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

• The reader reads; the exporter publishes. doca-telemetry is the library the user's application links to read hardware counters off a doca_dev. The application-side publishing of labeled metrics / OTLP logs is doca-telemetry-exporter/SKILL.md, a sibling library with its own skill. Wiring the exporter's API into a reader application (or this library's API into a publishing application) is the load-bearing first-app failure and the agent must surface the distinction BEFORE any code-level guidance.

• Cap-query is the only authority for "is this domain supported here". Each domain's support is bound to BOTH the DOCA version AND the active doca_devinfo. Never assert a domain or counter family is available from memory; the doca_telemetry_<domain>_cap_is_supported(devinfo) query (or the pci per-feature caps) is the runtime authority.

Capabilities and modes

DOCA Telemetry exposes six independent per-domain reader sub-libraries. Each is its own header, its own opaque context type, and its own doca_telemetry_<domain>_* symbol family. There is no single shared "telemetry context" object and no DOCA Core progress-engine / task surface here — each domain owns its own _create / _start / read / _stop / _destroy lifecycle directly on a doca_dev.

Role split — reader (this library) vs exporter (publisher). The two halves of DOCA telemetry are separate libraries, and the confusion between them is the #1 first-app failure.

Per-domain sub-libraries. The public surface is exactly these six. The agent must not invent a seventh, and must not invent a generic "telemetry collector" context. Exact symbol names are install-bound — confirm against the user's installed headers under $(pkg-config --variable=includedir doca-common) per the headers-win-over-docs rule in doca-version/SKILL.md.

Per-domain lifecycle. Every domain follows the same shape; the verbs are domain-specific (doca_telemetry_<domain>_*), not the generic DOCA Core doca_ctx_* surface:

Capability discovery — the only rule. Before assuming a domain (or, for phy / pci, a sub-area / feature) is on this install + this device, call the matching doca_telemetry_<domain>_cap_is_supported(devinfo) query (per the cross-cutting cap-query rule in doca-version CAPABILITIES.md ## Observability (doca-version/CAPABILITIES.md#observability)). The query is the runtime authority. Asserting "this device supports PHY FEC histograms" from memory without the cap query is the silent-fail case — when the device does not expose it, the read returns DOCA_ERROR_NOT_SUPPORTED and the user has no idea why. The agent MUST quote the queried values back to the user. doca_telemetry_pci has no single domain-level cap; query its per-feature _cap_*_is_supported functions for the specific PCI counter family you intend to read.

Path selection — reader vs the adjacent options. The reader is for reading DOCA hardware counters off a doca_dev. It is not the answer for every "telemetry" question; walk this rule before recommending reader setup.

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/SKILL.md. The body lives there; this skill does not duplicate it.

The per-domain reader overlay is:

• Use pkg-config --modversion doca-telemetry as the build-time anchor. Per doca-version TASKS.md ## configure (doca-version/TASKS.md#configure), this MUST match the other version sources in the four-way match. The set of domains — and the per-counter / per-sub-area surface each domain exposes — is bound to BOTH the DOCA version AND the active doca_devinfo; agent-memory limits are not authoritative and MUST be replaced with a doca_telemetry_<domain>_cap_is_supported query at runtime.

• The reader is distinct from the exporter across every release. When the user reports "I'm reading guides about doca-telemetry-exporter — is that this library?", the answer is no: that is the publishing side, with its own skill at doca-telemetry-exporter/SKILL.md. The two .pc files coexist on a normal install; using the wrong one for the user's intent is the load-bearing first-app failure and the agent must walk the role split (per ## Capabilities and modes) BEFORE picking a pkg-config module.

• doca-telemetry.pc plus doca-common.pc must both match doca_caps --version at the four-way-match check (per doca-version CAPABILITIES.md ## Version compatibility (doca-version/CAPABILITIES.md#version-compatibility)). A common partial-install pattern after a DOCA upgrade is that doca-telemetry.pc lingers from the previous release while doca-common.pc was refreshed; route to doca-version TASKS.md ## debug (doca-version/TASKS.md#debug) ladder step 2 before any reader-layer diagnosis.

• New per-domain counters / sub-areas and public API functions/constants appear across releases. A counter family, PHY sub-area, or API function/constant present on a newer DOCA may be absent on the user's install; the per-domain cap-query is the only safe way to discover what this install exposes. Never hardcode the available counter set, API surface, or constants in a build file or assume them from a docs page. DOCA 3.5 added PCC histogram query functions, PCI by-address read functions, PHY capability/get functions, and PHY firmware/management constants.

Error taxonomy

Per-domain-reader overlays on the cross-library DOCA_ERROR_* taxonomy. The cross-library taxonomy itself lives in doca-programming-guide CAPABILITIES.md ## Error taxonomy (doca-programming-guide/CAPABILITIES.md#error-taxonomy); the rows below are the reader surface meaning the agent must disambiguate before falling back to the cross-library response.

The agent's rule: never recommend a retry loop on DOCA_ERROR_* without first identifying which row above is the cause. NOT_SUPPORTED is the cap answer (surface it, don't retry); AGAIN wants a sample-window-aware retry, not a spin; the others want investigation.

PHY firmware and management firmware error codes

DOCA 3.5 adds PHY-specific error-code constants that are not part of the cross-library DOCA_ERROR_* taxonomy. Treat them as domain-specific status codes, not as DOCA_ERROR_* values.

They come in two families, DOCA_TELEMETRY_PHY_FW_* (link-level firmware status, e.g. link training or signal detection) and DOCA_TELEMETRY_PHY_MNG_FW_* (module / cable management status), plus DOCA_TELEMETRY_PHY_ERROR_CODE_CFG_REJECTED_INVALID_VS_SI. Read the exact set from doca_telemetry_phy.h on the installed release; do not list or hardcode them.

When a PHY read surfaces one of these constants, do not map it to the DOCA_ERROR_* rows above; surface the constant name and the PHY firmware/management firmware status it reports.

Observability

The reader's observability surface is the per-read return value plus the per-domain cap snapshot. There is no progress-engine completion stream and no external event transport — visibility comes from inspecting each read's doca_error_t and the configure-time cap-query results.

In DOCA 3.5 this surface extends to PCC histogram queries, PCI latency/management/perf counter reads, and PHY FEC/management/system/troubleshooting reads, plus the corresponding PCC and PHY cap queries. These are all doca_telemetry_<domain>_* read/query or doca_telemetry_<domain>_cap_* calls and are covered by the same two signals below.

Two primary signals the agent should reach for:

1. Per-read return. Every doca_telemetry_<domain>_* read / query call returns a doca_error_t. Inspect it on every call: success means the snapshot was read into the output struct; DOCA_ERROR_AGAIN means the snapshot / sample cycle is not ready (retry after the sample window per ## Safety policy); DOCA_ERROR_NOT_SUPPORTED means the device does not expose this domain / sub-area; any other DOCA_ERROR_* maps to a row in ## Error taxonomy.

2. Capability snapshot at configure time. The output of every doca_telemetry_<domain>_cap_* query is a snapshot of what this device exposes on this install before any read. Save it as the baseline; if a later read returns DOCA_ERROR_NOT_SUPPORTED or DOCA_ERROR_INVALID_VALUE, the diff against this snapshot is the bug, not the read call. Cap-query at configure time is the cheapest way to make a later capability-related error self-explanatory.

For the cross-cutting observability primitives (--sdk-log-level, the doca-<lib>-trace build flavor, the DOCA_LOG_LEVEL env var) see doca-debug CAPABILITIES.md ## Observability (doca-debug/CAPABILITIES.md#observability). For the install-tree observability (logger names, package layout) defer to doca-public-knowledge-map/SKILL.md.

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 (doca-hardware-safety/CAPABILITIES.md#safety-policy) (specifically ### Per-artifact overlay pattern (doca-hardware-safety/CAPABILITIES.md#per-artifact-overlay-pattern)). When the two layers disagree, the stricter wins; when either layer says STOP, the agent stops.

The reader's safety surface is cap-query-before-read + sample-window discipline + privilege for the specific counter domain. Each is the source of a specific first-app failure the agent must prevent.

• The reader is read-only. Do not invent a _publish() / _emit() / _register_schema() shape on any per-domain context; the per-domain API reads the device's counters and nothing more. If the user wants their app to ALSO publish the values it read to a monitoring pipeline, that requires a SEPARATE doca-telemetry-exporter/SKILL.md context inside the same application — not a method on the reader context.

• Cap-query before every domain you read. Each of the six domains is independently gated on the device + install. A device that exposes PHY counters may not expose DPA counters; query each domain you intend to read.

• adp_retx / diag clear-on-read is destructive to the counter state. When set_hist_clear_on_read / data_clear is enabled, reading resets the underlying counters. Surface this to the user before enabling it — a second reader (or a later read) sees the counters as they stand after the reset, not the cumulative total.

Deferred topic boundaries

This skill scopes itself to the DOCA Telemetry per-domain hardware-counter reader libraries. Adjacent topics the agent will get asked but should route elsewhere:

• The publishing / export side — doca-telemetry-exporter/SKILL.md is the sibling skill for the application-side publisher library. This skill is reader-side only; any "how do I emit / publish a counter value" question routes there.

• The DOCA Telemetry Service (DTS) — operating / deploying the service itself — owned by doca-dts.

• NetFlow / IPFIX / local-socket collector frameworks — the per-domain reader libraries do NOT expose a collector / schema-transport surface. Route any such question to a generic collector outside the DOCA family, to doca-telemetry-exporter/SKILL.md for publishing, or to doca-dts for productized aggregation.

• DOCA Core context internals — owned by doca-programming-guide/SKILL.md. Note the per-domain reader does NOT use the generic doca_ctx_* / progress-engine surface; it uses per-domain _create / _start / _stop / _destroy directly.

• Plain structured logging from the reader's own program — use doca-log; the per-domain cap-query discipline is overhead the user does not need for plain logs.

• Cross-cutting DOCA_ERROR_* taxonomy — owned by doca-programming-guide CAPABILITIES.md ## Error taxonomy (doca-programming-guide/CAPABILITIES.md#error-taxonomy). This skill adds the reader overlay (the NOT_SUPPORTED-means-domain-not-exposed rule and the AGAIN-means-snapshot-not-ready rule), not the taxonomy itself.

• Cross-cutting debug ladder (install / version / build / link / runtime / program / driver) — owned by doca-debug ## debug (doca-debug/TASKS.md#debug). This skill's ## debug overlays the runtime + program layers.