DOCA Telemetry Traceback Application
Scope boundaries
These requests are out of scope: say so, name the skill that owns
the request, and stop.
- the DOCA Telemetry Diag programming API and raw counter reads:
doca-telemetry/SKILL.md.
- DOCA install and bring-up:
doca-setup/SKILL.md.
- which DOCA version is installed, version consistency:
doca-version/SKILL.md.
- general DOCA orientation and documentation lookup:
doca-public-knowledge-map/SKILL.md.
Examples
- “Can I monitor telemetry trends on the DPU without streaming all raw data?” — in scope. Configure rules and sample history depth; do not use the DOCA Telemetry Diag API directly here.
- “The event log is empty even though a threshold was crossed.” — check rule
comparison_type and sample_history_depth; differential rules require depth samples before functioning.
- “How do I build only this application?” — use the Meson isolation flags; see the tasks companion.
- “I'm writing my own C code against the DOCA Telemetry Diag library to read counters.” — that part is
doca-telemetry's: the application uses Diag internally, but programming the Diag API is not this skill.
Name doca-telemetry for it and do not write Diag API code here; handle every other part of the request
as this skill describes (for example, --force-ownership still goes through doca-hardware-safety).
Quick facts
The authoritative source for the binary name, flags, and paths is the public
DOCA Telemetry Traceback guide for the release; confirm them with the installed
tool's --help before quoting any of them. As that guide describes it:
- Standalone application on a BlueField DPU or ConnectX NIC; four components:
DOCA Telemetry Diag instance, sample history circular buffer, rule
collection, and events log file.
- Configuration JSON fields:
diag_sample_period_ns, sample_history_depth,
data-ids array, and rules array. Rule types are
incremental_greater_than (inc_gt), differential_greater_than
(dt_gt), differential_less_than (dt_lt), greater_than (gt),
and less_than (lt).
- The circular buffer size is automatically doubled based on the requested
depth to ensure equal historical and active event data.
- Requires sudo/root privileges; mandatory
-d PCIe address and -r rules
JSON; optional --event-log and --force-ownership.
- Unsupported data IDs are reported; adjust inputs accordingly.
- The application stops if the actual sample size or period does not match
the requested parameters.
--force-ownership changes diag domain ownership; route any use of it
through doca-hardware-safety/SKILL.md.
Instructions
Follow Loading order below. Open the tasks companion for
configure / build / run / debug. Open the capabilities companion for
what the application monitors and logs. Do not open every companion file.
Where to start: This is a tool skill for invoking the DOCA Telemetry
Traceback application — the local telemetry monitoring and traceback logging
service that processes telemetry data on the device and writes event logs
when user-defined rules trigger. Open the tasks companion and start at
## configure for the JSON configuration and rule definitions, then
## run for compile and execution. Open the capabilities companion when
the question is what data can be monitored, what rules evaluate, and what
the event log contains. If the user has not installed DOCA yet, route to
doca-setup/SKILL.md first. If the user asks about version, route to
doca-version/SKILL.md. If any step changes hardware or firmware state
(e.g., --force-ownership), route to
doca-hardware-safety/SKILL.md.
How to use this skill. Read this file, then search the companion file
for the ## <name> heading the question needs and read that whole section.
Answer completely from it, quoting only its symbols and commands. Do not
browse docs; use the entry points in doca-public-knowledge-map. Give
environment checks as commands for the user's DOCA host. For out-of-scope
requests, name the skill that owns them and stop.
Compile and run commands are documented in the tasks companion; the
authoritative source is the public guide. The application is distributed as
source and must be compiled before execution. The source is located at
/opt/mellanox/doca/applications/telemetry/traceback/.
Example questions this skill answers well
The CLASSES of telemetry-traceback questions this skill is built to answer,
each with one worked example. The class is the load-bearing piece; the
worked example is one instance.
- “How do I set up local telemetry monitoring with traceback logging?” —
worked example: “I want to monitor
port_0_rx_bytes on the DPU and log
history before and after it exceeds 1 MB/s”. Answered by the JSON
configuration and rule definitions in the tasks companion.
- “What rule types are available and when do they activate/deactivate?” —
worked example: “I need a rule that triggers each time a counter increases
by a threshold, not just when it exceeds a fixed value”. Answered by the
rule definitions in the capabilities companion.
- “Why is my differential rule not triggering?” — worked example: “I
configured
differential_greater_than but the event log stays empty”.
Answered by the depth requirement and delta logic in the capabilities
companion.
- “How do I compile and run only this application?” — worked example: “I
want to build just the Telemetry Traceback app, not all DOCA applications”.
Answered by the Meson isolation flags in the tasks companion.
- “What does the event log contain when multiple events overlap?” —
worked example: “Two rules trigger at the same time; how are begin/end
markers written?”. Answered by the event log lifecycle in the capabilities
companion.
- “How do I know if my device supports the data IDs I configured?” —
worked example: “The application reports unsupported IDs; what do I do?”.
Answered by the unsupported data ID handling in the tasks companion.
When to load this skill
Load this skill when the user is — or the agent needs to — drive the DOCA
Telemetry Traceback application on a real host or BlueField Arm with DOCA
installed (or inside the public NGC DOCA container with the right device
passthrough). Concretely:
- Configuring JSON rules and data IDs for local telemetry monitoring.
- Compiling the application from source.
- Running the application with a PCIe address and rules file.
- Diagnosing an empty event log, unsupported data IDs, or sample size/period
mismatch.
- Understanding rule activation/deactivation semantics.
- Cross-checking event log output against configured rules.
Do not load this skill for general DOCA orientation, the DOCA Telemetry
Diag programming API, raw telemetry collection, DOCA install, or version
questions. For those, route to
doca-public-knowledge-map/SKILL.md,
doca-setup/SKILL.md, or
doca-version/SKILL.md.
What this skill provides
This is a thin loader. Substantive material lives in two companion files:
- the capabilities companion — what the application monitors and logs: the
four components, configuration schema, rule definitions with
activation/deactivation triggers, event log lifecycle, unsupported data ID
behavior, version overlay that redirects to
doca-version/SKILL.md, and the safety policy for
--force-ownership.
- the tasks companion — step-by-step workflows for the in-scope task verbs:
configure (JSON config, rule selection), build (Meson compile all or
only this app), run (execution syntax, root, PCIe address), debug
(empty log, unsupported IDs, sample mismatch), plus a Command appendix
that honors the bundle's
doca-structured-tools-contract/SKILL.md
preamble.
The skill assumes a host or BlueField where DOCA is already installed (or the
public NGC DOCA container is running with the right device passthrough) and
the operator has root privileges as required by the public guide.
What this skill deliberately does not ship
This skill is agent guidance, not a samples or scripts bundle. To keep the
boundary clean, it deliberately does not contain — and pull requests should
not add:
- Verbatim flag inventories, subcommand names, or output column names.
The public DOCA Telemetry Traceback guide and the installed
--help on the
user's version are the joint source of truth; copying them here pins the
skill to one release and silently rots when the application evolves. The
skill routes the agent at those sources instead.
- Pre-baked example output. Output is install-, version-, and
device-specific. A captured example will mislead an operator on a different
platform / state.
- Wrappers, parsers, or scripts in any language that consume the
application's output. The output format is documented; users who want to
script against it should read the live guide and write the parser against
their installed version.
- A
samples/ or reference/ subtree. This is a thin loader for a
documented DOCA artifact; substantive material lives on the public page and
in --help.
Loading order
- Read this skill first to confirm the user's question is in scope (the user
wants to monitor telemetry data locally and capture traceback event logs,
not use the DOCA Telemetry Diag programming API directly).
- For what the application monitors, the configuration schema, rule
definitions, event log lifecycle, unsupported data ID behavior, version
availability, and safety posture, see the capabilities companion.
- For the documented invocations and workflows —
configure, build,
run, debug, plus the Command appendix — see the tasks companion.
Related skills
doca-hardware-safety/SKILL.md — the
bundle's hardware/firmware state-change gate. The Telemetry Traceback
application is read-only for telemetry data, but the --force-ownership
flag changes diag domain ownership; route any use of that flag through this
skill before execution.
doca-version/SKILL.md — canonical DOCA
version-handling rules. The ## Version compatibility section in the
capabilities companion is a concise overlay that redirects here for the
body.
doca-setup/SKILL.md — env preparation,
install verification, and the I have no install yet path with the public
NGC DOCA container. This skill assumes its preconditions are satisfied.
doca-public-knowledge-map/SKILL.md
— routing to the public DOCA Telemetry Traceback guide and the rest of the
public DOCA documentation set. The canonical URL is reached via
doca-public-knowledge-map ## DOCA tools
(doca-public-knowledge-map/SKILL.md#doca-tools).
doca-structured-tools-contract/SKILL.md
— the bundle's detect → prefer → fall back → report contract for structured
helper tools. The Command appendix in the tasks companion honors this
contract.
1---2license: Apache-2.03name: doca-telemetry-traceback-application4description: >5 Use this skill when the operator is driving the DOCA Telemetry6 Traceback application to monitor telemetry data locally on a7 BlueField DPU or ConnectX NIC, detect long-term trends and8 threshold breaches with user-defined rules, and capture9 pre-event history plus active-event data to a log file. Trigger10 even when the user does not explicitly mention "DOCA Telemetry11 Traceback" — typical implicit phrasings include "monitor12 telemetry trends on the DPU without streaming all raw data",13 "log the samples before and after a threshold breach", "set up14 a rule that triggers when rx bytes/s exceeds 1M", "differential15 greater than rule on a data ID", "circular buffer of telemetry16 samples", or "traceback event log". Refuse and route elsewhere:17 the DOCA Telemetry Diag programming API and raw counter reads to18 doca-telemetry, DOCA install/bring-up to doca-setup, and version19 questions to doca-version.20metadata:21 source: https://skillmd.com/skills/nvidia/doca-telemetry-traceback-application22 author: NVIDIA <doca-feedback@nvidia.com>23 kind: tool24 doca_version: "3.5"25 tags:26 - doca27 - telemetry28 - traceback29 - monitoring30compatibility: >31 Requires DOCA SDK installed at /opt/mellanox/doca on Linux with a32 BlueField DPU or ConnectX NIC, plus root privileges to access33 hardware-level telemetry data. The application is distributed as34 source code and must be compiled before execution; the source is35 located at /opt/mellanox/doca/applications/telemetry/traceback/.36 Validation steps require a live DOCA install.37---3839# DOCA Telemetry Traceback Application4041## Scope boundaries4243These requests are out of scope: say so, name the skill that owns44the request, and stop.4546- the DOCA Telemetry Diag programming API and raw counter reads: `doca-telemetry/SKILL.md`.47- DOCA install and bring-up: `doca-setup/SKILL.md`.48- which DOCA version is installed, version consistency: `doca-version/SKILL.md`.49- general DOCA orientation and documentation lookup: `doca-public-knowledge-map/SKILL.md`.5051## Examples5253- **“Can I monitor telemetry trends on the DPU without streaming all raw data?”** — in scope. Configure rules and sample history depth; do not use the DOCA Telemetry Diag API directly here.54- **“The event log is empty even though a threshold was crossed.”** — check rule `comparison_type` and `sample_history_depth`; differential rules require depth samples before functioning.55- **“How do I build only this application?”** — use the Meson isolation flags; see the tasks companion.56- **“I'm writing my own C code against the DOCA Telemetry Diag library to read counters.”** — that part is57 `doca-telemetry`'s: the application uses Diag internally, but programming the Diag API is not this skill.58 Name `doca-telemetry` for it and do not write Diag API code here; handle every other part of the request59 as this skill describes (for example, `--force-ownership` still goes through `doca-hardware-safety`).6061## Quick facts6263The authoritative source for the binary name, flags, and paths is the public64DOCA Telemetry Traceback guide for the release; confirm them with the installed65tool's `--help` before quoting any of them. As that guide describes it:6667- Standalone application on a BlueField DPU or ConnectX NIC; four components:68 DOCA Telemetry Diag instance, sample history circular buffer, rule69 collection, and events log file.70- Configuration JSON fields: `diag_sample_period_ns`, `sample_history_depth`,71 `data-ids` array, and `rules` array. Rule types are72 `incremental_greater_than` (`inc_gt`), `differential_greater_than`73 (`dt_gt`), `differential_less_than` (`dt_lt`), `greater_than` (`gt`),74 and `less_than` (`lt`).75- The circular buffer size is automatically doubled based on the requested76 depth to ensure equal historical and active event data.77- Requires sudo/root privileges; mandatory `-d` PCIe address and `-r` rules78 JSON; optional `--event-log` and `--force-ownership`.79- Unsupported data IDs are reported; adjust inputs accordingly.80- The application stops if the actual sample size or period does not match81 the requested parameters.82- `--force-ownership` changes diag domain ownership; route any use of it83 through `doca-hardware-safety/SKILL.md`.8485## Instructions8687Follow Loading order below. Open the tasks companion for88configure / build / run / debug. Open the capabilities companion for89what the application monitors and logs. Do not open every companion file.9091**Where to start:** This is a tool skill for invoking the DOCA Telemetry92Traceback application — the local telemetry monitoring and traceback logging93service that processes telemetry data on the device and writes event logs94when user-defined rules trigger. Open the tasks companion and start at95`## configure` for the JSON configuration and rule definitions, then96`## run` for compile and execution. Open the capabilities companion when97the question is *what data can be monitored, what rules evaluate, and what98the event log contains*. If the user has not installed DOCA yet, route to99`doca-setup/SKILL.md` first. If the user asks about version, route to100`doca-version/SKILL.md`. If any step changes hardware or firmware state101(e.g., `--force-ownership`), route to102`doca-hardware-safety/SKILL.md`.103104**How to use this skill.** Read this file, then search the companion file105for the `## <name>` heading the question needs and read that whole section.106Answer completely from it, quoting only its symbols and commands. Do not107browse docs; use the entry points in `doca-public-knowledge-map`. Give108environment checks as commands for the user's DOCA host. For out-of-scope109requests, name the skill that owns them and stop.110111Compile and run commands are documented in the tasks companion; the112authoritative source is the public guide. The application is distributed as113source and must be compiled before execution. The source is located at114`/opt/mellanox/doca/applications/telemetry/traceback/`.115116## Example questions this skill answers well117118The CLASSES of telemetry-traceback questions this skill is built to answer,119each with one worked example. The class is the load-bearing piece; the120worked example is one instance.121122- **“How do I set up local telemetry monitoring with traceback logging?”** —123 worked example: *“I want to monitor `port_0_rx_bytes` on the DPU and log124 history before and after it exceeds 1 MB/s”*. Answered by the JSON125 configuration and rule definitions in the tasks companion.126- **“What rule types are available and when do they activate/deactivate?”** —127 worked example: *“I need a rule that triggers each time a counter increases128 by a threshold, not just when it exceeds a fixed value”*. Answered by the129 rule definitions in the capabilities companion.130- **“Why is my differential rule not triggering?”** — worked example: *“I131 configured `differential_greater_than` but the event log stays empty”*.132 Answered by the depth requirement and delta logic in the capabilities133 companion.134- **“How do I compile and run only this application?”** — worked example: *“I135 want to build just the Telemetry Traceback app, not all DOCA applications”*.136 Answered by the Meson isolation flags in the tasks companion.137- **“What does the event log contain when multiple events overlap?”** —138 worked example: *“Two rules trigger at the same time; how are begin/end139 markers written?”*. Answered by the event log lifecycle in the capabilities140 companion.141- **“How do I know if my device supports the data IDs I configured?”** —142 worked example: *“The application reports unsupported IDs; what do I do?”*.143 Answered by the unsupported data ID handling in the tasks companion.144145## When to load this skill146147Load this skill when the user is — or the agent needs to — drive the DOCA148Telemetry Traceback application on a real host or BlueField Arm with DOCA149installed (or inside the public NGC DOCA container with the right device150passthrough). Concretely:151152- Configuring JSON rules and data IDs for local telemetry monitoring.153- Compiling the application from source.154- Running the application with a PCIe address and rules file.155- Diagnosing an empty event log, unsupported data IDs, or sample size/period156 mismatch.157- Understanding rule activation/deactivation semantics.158- Cross-checking event log output against configured rules.159160Do **not** load this skill for general DOCA orientation, the DOCA Telemetry161Diag programming API, raw telemetry collection, DOCA install, or version162questions. For those, route to163`doca-public-knowledge-map/SKILL.md`,164`doca-setup/SKILL.md`, or165`doca-version/SKILL.md`.166167## What this skill provides168169This is a **thin loader**. Substantive material lives in two companion files:170171- the capabilities companion — what the application monitors and logs: the172 four components, configuration schema, rule definitions with173 activation/deactivation triggers, event log lifecycle, unsupported data ID174 behavior, version overlay that redirects to175 `doca-version/SKILL.md`, and the safety policy for176 `--force-ownership`.177- the tasks companion — step-by-step workflows for the in-scope task verbs:178 `configure` (JSON config, rule selection), `build` (Meson compile all or179 only this app), `run` (execution syntax, root, PCIe address), `debug`180 (empty log, unsupported IDs, sample mismatch), plus a `Command appendix`181 that honors the bundle's182 `doca-structured-tools-contract/SKILL.md`183 preamble.184185The skill assumes a host or BlueField where DOCA is already installed (or the186public NGC DOCA container is running with the right device passthrough) and187the operator has root privileges as required by the public guide.188189## What this skill deliberately does not ship190191This skill is **agent guidance**, not a samples or scripts bundle. To keep the192boundary clean, it deliberately does not contain — and pull requests should193not add:194195- **Verbatim flag inventories, subcommand names, or output column names.**196 The public DOCA Telemetry Traceback guide and the installed `--help` on the197 user's version are the joint source of truth; copying them here pins the198 skill to one release and silently rots when the application evolves. The199 skill routes the agent at those sources instead.200- **Pre-baked example output.** Output is install-, version-, and201 device-specific. A captured example will mislead an operator on a different202 platform / state.203- **Wrappers, parsers, or scripts** in any language that consume the204 application's output. The output format is documented; users who want to205 script against it should read the live guide and write the parser against206 their installed version.207- **A `samples/` or `reference/` subtree.** This is a thin loader for a208 documented DOCA artifact; substantive material lives on the public page and209 in `--help`.210211## Loading order2122131. Read this skill first to confirm the user's question is in scope (the user214 wants to monitor telemetry data locally and capture traceback event logs,215 not use the DOCA Telemetry Diag programming API directly).2162. **For what the application monitors, the configuration schema, rule217 definitions, event log lifecycle, unsupported data ID behavior, version218 availability, and safety posture, see the capabilities companion.**2193. **For the documented invocations and workflows — `configure`, `build`,220 `run`, `debug`, plus the `Command appendix` — see the tasks companion.**221222## Related skills223224- `doca-hardware-safety/SKILL.md` — the225 bundle's hardware/firmware state-change gate. The Telemetry Traceback226 application is read-only for telemetry data, but the `--force-ownership`227 flag changes diag domain ownership; route any use of that flag through this228 skill before execution.229- `doca-version/SKILL.md` — canonical DOCA230 version-handling rules. The `## Version compatibility` section in the231 capabilities companion is a concise overlay that redirects here for the232 body.233- `doca-setup/SKILL.md` — env preparation,234 install verification, and the *I have no install yet* path with the public235 NGC DOCA container. This skill assumes its preconditions are satisfied.236- `doca-public-knowledge-map/SKILL.md`237 — routing to the public DOCA Telemetry Traceback guide and the rest of the238 public DOCA documentation set. The canonical URL is reached via239 `doca-public-knowledge-map ## DOCA tools`240 (`doca-public-knowledge-map/SKILL.md#doca-tools`).241- `doca-structured-tools-contract/SKILL.md`242 — the bundle's detect → prefer → fall back → report contract for structured243 helper tools. The Command appendix in the tasks companion honors this244 contract.