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 / 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 and start at ## 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 for the snapshot → analyze → visualize loop, then ## 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 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 first; if the user has no running doca-flow application yet, route to doca-flow — 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 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
  • the configure walk in 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 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
  • 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), 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.

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-flow, doca-setup, or doca-flow-perf.