/doca-flow-tune

license: Apache-2.0
name: doca-flow-tune
description: >
  Use this skill when the user is tuning a live or captured
  `doca-flow` pipeline with `doca_flow_tune` — snapshotting
  pipe / counter / KPI state, picking a tuning axis (rule
  placement, resource hints / table sizing, HW-offload mode)
  and a matching measurement (rule-install rate, lookup latency,
  hardware-counter delta), running offline or online (read-only
  or state-changing) modes, reading the dumper CSV / analyze
  JSON / visualize mermaid, or applying a recommendation back
  into the Flow program. Trigger even when the user does
  not explicitly mention "doca_flow_tune" — typical implicit
  phrasings include "Flow rule-install rate is low on
  BlueField", "table sizing looks wrong for this pipe", "tune
  visualize step is empty", "before/after
  counters don't move", or "which doca-flow knob does this
  recommendation hit". Refuse and route elsewhere for measuring
  baseline numbers (doca-flow-perf, doca-flow-dpa-perf), writing
  the doca-flow application, DOCA install, or streaming Flow
  telemetry — those belong to other skills.
metadata:
  kind: tool
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, plus a running or captured `doca-flow`
  application to observe. Reads the user's local install via
  `pkg-config doca-flow` and the shipped `flow_tune_cfg*.json`
  templates and `scripts/` directory under /opt/mellanox/doca.

DOCA Flow Tune (`doca_flow_tune`)

> **Subcommand surface correction (Run-12, verified Run-13 > against doca/tools/flow_tune/src/tune/common/tune_config.cpp).** > `doca_flow_tune` is a single binary whose **role on a given > invocation is determined by which of five top-level > subcommands** the user picks — `dump`, `monitor`, `web`, > `analyze`, `visualize` (case-insensitive on the CLI; > uppercased in this skill for readability). All five names > are registered via `doca_argp_cmd_set_name(...)` in > `tune_config.cpp` (lines 1799 / 1860 / 1896 / 2074 / 2111); > `analyze` further accepts `import` / `export` / `packet_trace` > / `sim_timing` sub-subcommands. The `dump` / `monitor` / `web` > subcommands run the binary in **server-attached online mode** > against a live `doca-flow` application reached over a Unix- > domain socket whose path lives in `network.server_uds` of the > shipped `flow_tune_cfg*.json`; the `analyze` / `visualize` > subcommands run in **offline / captured-snapshot mode** against > JSON / CSV files the online modes previously dropped into the > configured `outputs_directory`. The rest of this skill (and > [`CAPABILITIES.md`](CAPABILITIES.md) / [`TASKS.md`](TASKS.md)) > uses the legacy *"server role / online mode / offline mode"* > framing — that framing is internally consistent with the > subcommand surface here: *server role* = a server-attached > online subcommand (`dump`/`monitor`/`web`); *online mode* = > any of `dump`/`monitor`/`web`; *offline mode* = > `analyze`/`visualize`. Treat the subcommand name as the > primary handle; treat *server/online/offline* as the > downstream behavioral consequence of the subcommand pick.

**Where to start:** This is a tool skill for invoking `doca_flow_tune`, the unified DOCA Flow tuning tool. Open [`TASKS.md`](TASKS.md) and start at [`## configure`](TASKS.md#configure) to commit to the three-axis decision (target Flow pipeline × tuning axis × measurement) and pick offline vs online vs server-attach mode, then [`## run`](TASKS.md#run) for the snapshot → analyze → visualize loop, then [`## test`](TASKS.md#test) for the smoke-before-bulk overlay that gates any state-changing application of a tuning recommendation back into the Flow application's code. Open [`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what state `doca_flow_tune` can observe and recommend on*, *how its server / client roles fit inside the single artifact*, *which DOCA version the tool ships in*, or *how to interpret the dumper / monitor / analyze / visualize outputs without fooling yourself*. If DOCA is not installed, route to [`doca-setup`](../../doca-setup/SKILL.md) first; if the user has no running `doca-flow` application yet, route to [`doca-flow`](../../libs/doca-flow/SKILL.md) — flow-tune does not create pipes, it observes and recommends on top of pipes the library already created.

Example questions this skill answers well

The CLASSES of `doca_flow_tune` 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.

• **"Should I reach for `doca-flow-tune` or `doca-flow-perf` for

this question?"** — worked example: *"my doca-flow service runs on a BlueField-3 and I think the rule-install rate is below what the device can sustain; do I measure first or tune first?"*. Answered by the *tune vs perf* boundary in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) and the routing into [`doca-flow-perf`](../doca-flow-perf/SKILL.md) for baselines vs this skill for optimization on top of a measured baseline.

• **"Capture a snapshot of a live `doca-flow` pipeline's hardware

and software counters without touching the dataplane."** — worked example: *"I want a side-effect-free dumper / monitor run against the running Flow ports for an operations-rate profile"*. Answered by the snapshot flow in [`TASKS.md ## run`](TASKS.md#run) plus the read-only-by-default posture in [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy).

• **"Pick the right tuning axis — rule placement, resource hints,

or hardware-offload mode — for the question I actually have."** — worked example: *"my Flow pipe's rule-install rate is low; is this a placement question or a table-sizing question?"*. Answered by the three-axis configuration in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabil