/doca-telemetry-traceback-application

license: Apache-2.0
name: doca-telemetry-traceback-application
description: >
  Use this skill when the operator is driving the DOCA Telemetry
  Traceback application to monitor telemetry data locally on a
  BlueField DPU or ConnectX NIC, detect long-term trends and
  threshold breaches with user-defined rules, and capture
  pre-event history plus active-event data to a log file. Trigger
  even when the user does not explicitly mention "DOCA Telemetry
  Traceback" — typical implicit phrasings include "monitor
  telemetry trends on the DPU without streaming all raw data",
  "log the samples before and after a threshold breach", "set up
  a rule that triggers when rx bytes/s exceeds 1M", "differential
  greater than rule on a data ID", "circular buffer of telemetry
  samples", or "traceback event log". Refuse and route elsewhere:
  the DOCA Telemetry Diag programming API and raw counter reads to
  doca-telemetry, DOCA install/bring-up to doca-setup, and version
  questions to doca-version.
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: tool
  doca_version: "3.5"
  tags:
    - doca
    - telemetry
    - traceback
    - monitoring
compatibility: >
  Requires DOCA SDK installed at /opt/mellanox/doca on Linux with a
  BlueField DPU or ConnectX NIC, plus root privileges to access
  hardware-level telemetry data. The application is distributed as
  source code and must be compiled before execution; the source is
  located at /opt/mellanox/doca/applications/telemetry/traceback/.
  Validation steps require a live DOCA install.

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