doca-flow-tune

# 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#capabilities-and-modes)
  + the configure walk in
  [`TASKS.md ## configure`](TASKS.md#configure).
- **"How do `doca_flow_tune`'s server role and client / consumer
  role fit together inside the single artifact?"** — worked
  example: *"I keep reading about a Flow Tune server and a Flow
  Tune client; which binary am I running?"*. Answered by the
  *one binary, two roles* breakdown in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  and the corresponding routing in
  [`TASKS.md ## configure`](TASKS.md#configure).
- **"How do I take a recommended parameter change from flow-tune
  back into my doca-flow application without breaking the
  dataplane?"** — worked example: *"the analyze step suggests a
  different table sizing for my pipe; how do I apply it?"*.
  Answered by the *recommendation → minimum-diff modification of
  the Flow program* loop in
  [`TASKS.md ## modify`](TASKS.md#modify) and the
  smoke-before-bulk rule in
  [`TASKS.md ## test`](TASKS.md#test).
- **"`doca_flow_tune` reports nothing / disagrees with the Flow
  app / cannot attach — what does that mean?"** — worked example:
  *"the tool runs but the visualize step produces an empty
  mermaid diagram"*. Answered by the layered error taxonomy in
  [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy)
  + [`TASKS.md ## debug`](TASKS.md#debug).

## Audience

This skill serves **external operators, performance engineers,
DOCA Flow application developers, and AI agents who need to
understand, characteri