About this skill
---
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#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, characterize, or improve a running `doca-flow`
pipeline's behavior on the user's actual install and device**.
Concretely:
- A platform operator running a `doca-flow` service on BlueField
who wants a read-only snapshot of which pipes exist and how
their hardware / software counters are progressing before
recommending any change.
- A performance engineer who already has a `doca-flow-perf`
baseline number and wants to turn the *measurement* into an
*optimization* — pick a tuning axis and identify which knob in
the doca-flow program is the lever for it.
- A DOCA Flow application developer who wants the offline analyze
+ visualize loop to understand a pipe layout without
re-instrumenting the Flow program.
- An AI agent driving the *"is this Flow pipeline behaving as
expected, and would a non-mutating tuning hint help"* triage
step before recommending any code change to the Flow program.
It is **not** for users debugging the `doca_flow_tune` source code,
**not** a substitute for the live public DOCA Flow Tune guide on
`docs.nvidia.com`, **not** the right place to learn the
`doca-flow` API (that audience belongs in
[`doca-flow`](../../libs/doca-flow/SKILL.md)), and **not** the
right place for baseline *measurement* methodology — that belongs
to [`doca-flow-perf`](../doca-flow-perf/SKILL.md).
`doca_flow_tune` is shipped as a **single tool** (one binary plus
its companion analyzer / visualizer scripts and JSON config
templates) — the historical *server* and *client* roles live
inside this one artifact, not in two separate executables. The
skill uses the same `kind: tool` three-file shape as the rest
of the bundle so the agent's task-verb contract
(`configure / build / modify / run / test / debug`) is uniform
across libraries, services, and tools.
## Language scope
This skill governs invocation, output interpretation, and
recommendation-to-code-change routing for the C / C++ DOCA Flow
application that `doca_flow_tune` observes. The tool itself is
not a programming target — there is no public API the agent is
supposed to link against; what the agent and the user do with the
tool is *configure JSON, run, read the outputs, propose minimum-
diff changes to the surrounding `doca-flow` program in the
program's own language*. For the `doca-flow` API the
recommendations route back into, see
[`doca-flow CAPABILITIES.md`](../../libs/doca-flow/CAPABILITIES.md);
for cross-language application patterns, see
[`doca-programming-guide`](../../doca-programming-guide/SKILL.md).
## When to load this skill
Load this skill when the user is — or the agent needs to — invoke
`doca_flow_tune` against a running or planned `doca-flow`
application (on host or BlueField Arm, or inside the public NGC
DOCA container with the matching Flow trace-build flavor) to
characterize, dump, visualize, analyze, or tune that pipeline.
Concretely:
- Picking *which* role of `doca_flow_tune` to engage (offline
analyze / visualize on a captured config + state, online
dumper / monitor against the live Flow app, or attach-to-app
server-role usage when the Flow application links the
documented tune server entry points).
- Picking *which* tuning axis to ask about (rule placement,
resource hints / table sizing, or hardware-offload-mode) for a
candidate workload.
- Picking *which* measurement axis to compare against (rule-install
rate, lookup latency, hardware-counter delta) — the three are
not interchangeable and the chosen axis should be the same one a
prior `doca-flow-perf` baseline named.
- Capturing a documented before / after pair around a proposed
Flow-program change (the documented JSON config file path, the
command line, the DOCA version, the device, the as-deployed
environment, the full unredacted dumper / analyzer / visualizer
output).
- Diagnosing why a tune session produced empty output, a
visualize step rendered a degenerate diagram, or an analyze
recommendation does not match what the live counters say.
Do **not** load this skill for general DOCA orientation, Flow
program API work, install, or pure measurement methodology.
For those, route to
[`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md),
[`doca-flow`](../../libs/doca-flow/SKILL.md),
[`doca-setup`](../../doca-setup/SKILL.md), or
[`doca-flow-perf`](../doca-flow-perf/SKILL.md).
## What this skill provides
This is a **thin loader**. Substantive material lives in two
companion files:
- `CAPABILITIES.md` — what `doca_flow_tune` observes and
recommends on: the unified-artifact decomposition (server role
+ client / consumer role inside one binary), the three-axis
configuration model (tuning axis × measurement × scope: which
pipe / port / app), the documented offline / online / attach
modes, the JSON configuration-file shape (the publicly-shipped
`flow_tune_cfg_public.json` template plus its hardware-only and
software-only variants), the dumper / monitor / analyze /
visualize output surfaces, the version overlay (this tool rides
the `doca-flow` library version it observes; the canonical
rules live in [`doca-version`](../../doca-version/SKILL.md)),
the layered error taxonomy
(config-syntax / attach-failed / pipe-not-found /
measurement-unsound / recommendation-unactionable / version /
cross-cutting), the observability posture (the tool *is* an
observability primitive for the Flow pipeline), and the safety
policy that makes any mutating application of a recommendation
high-stakes because the recommendation lands in live Flow state.
- `TASKS.md` — step-by-step workflows for the in-scope task verbs:
`install` (route to setup; the binary is shipped),
`configure` (the three-axis decision + JSON config + mode pick),
`build` (route to install; the binary is shipped), `modify`
(apply a recommendation back to the Flow program via minimum-
diff), `run` (the snapshot → analyze → visualize flow), `test`
(the eval loop — warm-up, steady-state, before / after pair,
client / server / Flow version match), `debug` (walk the error
taxonomy layer by layer), `use` (the agent-side workflow for
consuming flow-tune output), plus a `Deferred task verbs` block
and a `Command appendix`.
The skill assumes a host where DOCA is already installed (or the
public NGC DOCA container is running) and a `doca-flow`
application is already created and validated per the
[`doca-flow`](../../libs/doca-flow/SKILL.md) skill. Without those
preconditions, the tune session has nothing to observe.
## 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, JSON config field
names, or default endpoint paths quoted as the contract.** The
public DOCA Flow Tune guide on `docs.nvidia.com` (reached via
[`doca-public-knowledge-map ## DOCA tools`](../../doca-public-knowledge-map/SKILL.md#doca-tools))
and the installed `--help` on the user's version are the joint
source of truth; the shipped `flow_tune_cfg*.json` templates on
the user's install are the second source for the JSON schema.
Copying them here pins the skill to one release and silently
rots when the tool evolves.
- **Pre-baked example output (dumper CSV columns, analyzer JSON
field names, visualizer mermaid output).** Output is install-,
device-, firmware-, NUMA-, Flow-pipe-, and DOCA-version-specific;
a captured example pinned to one platform misleads operators on
a different platform / version.
- **Wrappers, parsers, or scripts** in any language that consume
flow-tune output. The output formats are documented and the
shipped `scripts/` directory on the user's install contains
vendor-provided helpers (e.g. `flow_json_diff.py`,
`flow_mermaid_diff.py`, `hw_counters_csv_analyzer.py`); if a
user wants to script against the outputs, the right answer is
*"read the shipped scripts on your installed version"*.
- **Pre-baked tuning recommendations.** Recommendations from this
tool are install-, device-, firmware-, and workload-specific;
shipping one for *"hairpin pipes"* or *"NAT pipes"* misleads
operators applying it to a different pipe. The agent always
re-derives the recommendation from the user's actual session.
- **A `samples/`, `templates/`, or `reference/` subtree.** Mock or
incomplete tuning recipes in this skill's tree are misleading;
operators read them as production-grade.
## Loading order
1. Read this `SKILL.md` first to confirm the user's question is
in scope (the user actually wants to invoke `doca_flow_tune`
against a `doca-flow` pipeline, not measure baseline perf or
learn the Flow API).
2. **For what `doca_flow_tune` observes, the one-binary / two-role
decomposition, the three-axis model, the version overlay, the
error taxonomy, observability surface, and safety posture,
see [CAPABILITIES.md](CAPABILITIES.md).**
3. **For the documented invocations and the snapshot → analyze →
visualize → propose → smoke workflow — `install`, `configure`,
`build`, `modify`, `run`, `test`, `debug`, `use` — see
[TASKS.md](TASKS.md).**
## Related skills
- [`doca-flow`](../../libs/doca-flow/SKILL.md) — the **base
library** whose pipeline this tool observes and tunes. The
pipe / entry / rule surface flow-tune reports on is created by
`doca-flow` program code; recommendations route back into that
program via the universal modify-a-sample workflow.
- [`doca-flow-perf`](../doca-flow-perf/SKILL.md) — the sibling
*measurement* tool. The rule is: `doca-flow-perf` measures
baselines; `doca-flow-tune` recommends optimizations on top.
An agent that reaches for tune without a baseline number from
perf is optimizing in the dark; an agent that reaches for perf
without a question is benchmarking for the sake of it.
- [`doca-flow-dpa-perf`](../doca-flow-dpa-perf/SKILL.md) — the
DPA-offloaded variant of Flow perf. Relevant when the Flow
pipeline the user is tuning runs through a DPA-offload path;
the baseline comes from there, not from host-side
`doca-flow-perf`.
- [`doca-flow-grpc-server`](../doca-flow-grpc-server/SKILL.md) —
the remote-control gRPC surface for `doca-flow`. Programmatic
Flow rule management lives there; flow-tune's recommendations
may be applied through that surface when the operator's
control plane is remote.
- [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md)
— routing to the public DOCA Flow Tune page on `docs.nvidia.com`
and the rest of the public DOCA documentation set.
- [`doca-version`](../../doca-version/SKILL.md) — the canonical
version-detection chain, four-way match, NGC semantics, and
headers-win-over-docs rule. The
[`## Version compatibility`](CAPABILITIES.md#version-compatibility)
overlay in this skill is a thin extension on top.
- [`doca-debug`](../../doca-debug/SKILL.md) — the cross-cutting
debug ladder. Flow-tune surfaces *its own* error taxonomy; when
the cause turns out to be below DOCA (driver, firmware, NUMA),
the tune taxonomy hands off to `doca-debug`.
- [`doca-structured-tools-contract`](../../doca-structured-tools-contract/SKILL.md)
— the bundle's detect → prefer → fall back → report contract.
The Command appendix in [`TASKS.md`](TASKS.md) honors it.
- [`doca-setup`](../../doca-setup/SKILL.md) — env preparation,
install verification, hugepages, NUMA, and the *I have no
install yet* path with the public NGC DOCA container.
- [`doca-hardware-safety`](../../doca-hardware-safety/SKILL.md) —
the cross-cutting hardware-safety meta-policy this skill's
`## Safety policy` overlays.