doca-flow-tune

# DOCA Flow Tune (`doca_flow_tune`) ## Examples - **"Flow rule-install rate is low on BlueField."** — this is in scope. Snapshot then pick a tuning axis; do not replace this with a flow-perf baseline run. - **"Tune visualize step is empty."** — check the dumper JSON/CSV / analyze JSON before changing the Flow program. ## Instructions Follow Loading order below. Open the tasks companion for configure / tune / debug. Open the capabilities companion for online vs offline modes. Do not open every companion file. > **Command surface (DOCA 3.5 public Flow Tune guide).** > `doca_flow_tune` is a single binary whose **role on a given > invocation is determined by which of three top-level > commands** the user picks — `monitor`, `analyze`, > `visualize` (confirm with `--help` on the installed > version). `dump`, `web`, `import`, and `sim_timing` are not > in the 3.5 guide; do not invoke them. > Counter dumping is part of `monitor` (`--enable-dump`, or the > `background` sub-command for dumping without screen output), > not a separate command; `analyze` accepts the `export` and > `packet-trace` sub-commands (hyphenated). `monitor` and > `analyze` 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`; `visualize` (and offline > analysis of a previously exported pipeline file) runs in > **offline / captured-snapshot mode** against JSON / CSV files > the online commands previously dropped into the > configured `outputs_directory`. The rest of this skill (and > the capabilities companion / the tasks companion) > uses the legacy *"server role / online mode / offline mode"* > framing — that framing is internally consistent with the > command surface here: *server role* = a server-attached > online command (`monitor`, `analyze export` / `analyze > packet-trace`); *online mode* = any of those; *offline mode* = > `visualize` over captured files. Treat the command 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 the tasks companion 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 the capabilities companion 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/SKILL.md` first; if the user has no running `doca-flow` application yet, route to `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 the capabilities companion and the routing into `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 the tasks companion plus the read-only-by-default posture in the capabilities companion. - **"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 the capabilities companion + the configure walk in the tasks companion. - **"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 the capabilities companion and the corresponding routing in the tasks companion. - **"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 the tasks companion and the smoke-before-bulk rule in the tasks companion. - **"`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 the capabilities companion + the tasks companion. ## 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: - An operator wanting a read-only snapshot of which pipes exist and how their hardware / software counters progress before recommending any change. - A performance engineer who has a `doca-flow-perf` baseline and wants to turn *measurement* into *optimization* — pick a tuning axis and identify which knob in the doca-flow program is the lever. - A Flow developer using the offline analyze + visualize loop to understand a pipe layout without re-instrumenting the program. - An AI agent driving the *"is this pipeline behaving as expected, and would a non-mutating tuning hint help"* triage step. It is **not** for users debugging the `doca_flow_tune` source code, **not** a substitute for the live public DOCA Flow Tune guide, **not** the place to learn the `doca-flow` API (see `doca-flow/SKILL.md`), and **not** the place for baseline *measurement* methodology — that belongs to `doca-flow-perf/SKILL.md`. `doca_flow_tune` is shipped as a **single tool** (one binary plus companion analyzer / visualizer scripts and JSON config templates) — the historical *server* and *client* roles live inside this one artifact, not in two executables. It uses the same `kind: tool` three-file shape as the rest of the bundle. ## Language scope This skill governs invocation, output interpretation, and recommendation-to-code-change routing for the DOCA Flow application `doca_flow_tune` observes. The tool is not a programming target — there is no public API to link against; the workflow is *configure JSON, run, read outputs, propose minimum- diff changes to the surrounding `doca-flow` program*. For the `doca-flow` API the recommendations route back into, see `doca-flow/SKILL.md`; for cross-language application patterns, see `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 to characterize, dump, visualize, analyze, or tune that pipeline. Concretely: - Picking *which* role to engage (offline analyze / visualize on a captured config + state, online dumper / monitor against the live app, or attach-to-app server-role usage). - Picking *which* tuning axis to ask about (rule placement, resource hints / table sizing, hardware-offload-mode). - Picking *which* measurement axis to compare against (rule-install rate, lookup latency, hardware-counter delta) — not interchangeable; use the axis a prior `doca-flow-perf` baseline named. - Capturing a documented before / after pair around a proposed Flow-program change (JSON config path, command line, DOCA version, device, environment, unredacted tool output). - Diagnosing an empty session, a degenerate visualize diagram, or an analyze recommendation that contradicts live counters. Do **not** load this skill for general DOCA orientation, Flow program API work, install, or pure measurement methodology — route to `doca-public-knowledge-map/SKILL.md`, `doca-flow/SKILL.md`, `doca-setup/SKILL.md`, or `doca-flow-perf/SKILL.md`. ## What this skill provides This is a **thin loader**. Substantive material lives in two companion files: - the capabilities companion — 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/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. - the tasks companion — 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.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 (reached via `doca-public-knowledge-map ## DOCA tools` (`doca-public-knowledge-map/SKILL.md#doca-tools`)) and the installed `--help` are the joint source of truth; the shipped `flow_tune_cfg*.json` templates are the second source for the JSON schema. Copying them here rots when the tool evolves. - **Pre-baked example output (dumper CSV columns, analyzer JSON field names, visualizer mermaid output).** Output is install-, device-, firmware-, and version-specific; a captured example pinned to one platform misleads operators elsewhere. - **Wrappers, parsers, or scripts** that consume flow-tune output. 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`); the right answer is *"read the shipped scripts on your installed version"*. - **Pre-baked tuning recommendations.** Recommendations are install-, device-, firmware-, and workload-specific; the agent always re-derives them from the user's actual session. - **A `samples/`, `templates/`, or `reference/` subtree.** Mock tuning recipes read as production-grade and mislead. ## Loading order 1. Read this skill 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 the capabilities companion.** 3. **For the documented invocations and the snapshot → analyze → visualize → propose → smoke workflow — `install`, `configure`, `build`, `modify`, `run`, `test`, `debug`, `use` — see the tasks companion.** ## Related skills - `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/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-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/SKILL.md` — 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/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/SKILL.md` — the bundle's detect → prefer → fall back → report contract. The Command appendix in the tasks companion honors it. - `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/SKILL.md` — the cross-cutting hardware-safety meta-policy this skill's `## Safety policy` overlays.