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.
Instrucciones de origen · Vista previa de solo lectura
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 / 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 and
start at to commit to the
three-axis decision (target Flow pipeline × tuning axis ×
measurement) and pick offline vs online vs server-attach mode, then
for the snapshot → analyze → visualize
loop, then for the smoke-before-bulk
overlay that gates any state-changing application of a tuning
recommendation back into the Flow application's code. Open
when the question is , , , or . If DOCA is
not installed, route to
first; if the user has
no running application yet, route to
— flow-tune does not
create pipes, it observes and recommends on top of pipes the
library already created.
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
and the routing into
doca-flow-perf 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 plus the read-only-by-default
posture in
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
"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
and the corresponding routing in
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 and the
smoke-before-bulk rule in
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
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), and not the
right place for baseline measurement methodology — that belongs
to doca-flow-perf.
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;
for cross-language application patterns, see
doca-programming-guide.
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.
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),
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 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)
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
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).
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.
For the documented invocations and the snapshot → analyze →
visualize → propose → smoke workflow — install, configure,
build, modify, run, test, debug, use — see
TASKS.md.
Related skills
doca-flow — 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 — 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 — 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 —
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
— routing to the public DOCA Flow Tune page on docs.nvidia.com
and the rest of the public DOCA documentation set.
doca-version — the canonical
version-detection chain, four-way match, NGC semantics, and
headers-win-over-docs rule. The
## Version compatibility
overlay in this skill is a thin extension on top.
doca-debug — 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.
