Doca Flow Tune

DOCA Flow Tune — Capabilities

Where to start: doca_flow_tune is a unified DOCA tool that observes and recommends parameter changes on a live or captured doca-flow pipeline. The pattern overview below names the recurring doca_flow_tune-class questions. Pick the pattern first, then drill into the H2 that owns the substance. For the how of executing each pattern, jump to TASKS.md. For the doca-flow API surface that created the pipeline this tool tunes, see doca-flow/CAPABILITIES.md.

This file is loaded by SKILL.md. It documents what doca_flow_tune is, what it observes and what it recommends on, how its server role and client / consumer role decompose inside a single binary, what versions it ships in, what its layered error and observability surfaces look like, and the safety posture the tool's role at the edge of a live dataplane forces.

Pattern overview

Every doca_flow_tune question this skill teaches resolves into one of SIX patterns. The patterns are CLASSES — they apply across every doca-flow application a tune session can attach to, not one specific pipeline.

Two cross-cutting rules that apply to every pattern above:

• doca_flow_tune is one binary, two internal roles. The historical Flow Tune Server and Flow Tune Tool (client) live inside this one artifact: there is one binary on disk, one package, one version, and the roles decompose inside the invocation surface — not across two separately-shipped CLIs. Recommendations that frame "the tune server" and "the tune client" as different artifacts are categorically wrong; they are different modes of the same artifact and the agent must surface that.

• Measure, then tune. The most common up-front mistake is recommending a parameter change before a monitor-mode baseline exists, or comparing a before / after pair on different measurement axes. An agent that does not name the baseline and its axis has silently conflated optimization with guessing.

Capabilities and modes

doca_flow_tune is shipped as a single CLI tool in the DOCA install (/opt/mellanox/doca/tools/doca_flow_tune), driven by a JSON configuration file whose shape is documented in the configuration-file example in the public DOCA Flow Tune guide. There is no daemon process the operator runs as an independent service and no library to link against for the tool itself — the entire interaction model is write a JSON config, invoke the binary, read the printed and / or CSV / mermaid / JSON output, propose a minimum-diff change back to the surrounding doca-flow program.

Measure, then tune

doca_flow_tune covers both halves of a tuning loop on the user's own pipeline:

The rule: no recommendation without a baseline, and before / after on the same axis. An optimization without a measured baseline is optimizing in the dark.

One binary, two internal roles

doca_flow_tune exposes two internal roles inside the one artifact:

The two roles share one binary and one JSON configuration file. Picking which role a session engages is a configuration decision (which sections of the JSON config are populated, which mode flag is passed on the command line) — not a binary-choice decision. Recommendations that frame "install the server package, then the client package" are categorically wrong; the DOCA install ships the unified tool and there is one binary on disk.

Three-axis configuration

Every concrete doca_flow_tune session commits to a point in three independent axes. Skipping any axis produces a session that inspects or tunes the wrong thing under unstated assumptions.

Operating modes

Per the public Flow Tune guide and the live invocation surface, doca_flow_tune exposes three operating modes the agent should name explicitly:

The exact CLI mode flag names, the full JSON config schema, and the documented pipeline-description file format live in 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 in the installed --help on the user's version. The skill deliberately does not pin them — see SKILL.md ## What this skill deliberately does not ship.

Version compatibility

For the canonical DOCA version-detection chain, the four-way match rule, NGC container semantics, and the headers-win-over-docs rule, see doca-version/SKILL.md. The body lives there; this skill does not duplicate it.

The doca_flow_tune-specific overlay is:

• The tool rides the doca-flow library version it observes. The tune binary, the Flow library *.so the application links, and (when the attach role is used) the application's compile- time Flow headers must all come from the same DOCA install. Cross-train pairings (a tune binary from one DOCA train looking at a Flow application linked against a different train's *.so) are partial-install hazards per doca-version CAPABILITIES.md ## Version compatibility (doca-version/CAPABILITIES.md#version-compatibility), and the agent must surface the mismatch rather than paper over it. The right answer for "the tool runs but the visualize step produces wrong-shaped output" is to confirm the four-way match first per doca-version TASKS.md ## test (doca-version/TASKS.md#test).

• JSON config / output stability is not contractually frozen. The JSON configuration field inventory, the dumper CSV column order, the analyze JSON schema, and the visualize mermaid layout can shift across releases. Agents that need to consume tune output programmatically should prefer the structured-helper contract in doca-structured-tools-contract ## Schemas (doca-structured-tools-contract/SKILL.md#schemas) when present and re-verify the textual layout against the user's installed --help and the guide when absent.

• Per-platform support varies. The documented BlueField generation and host-side support set for Flow tuning varies per release; do not copy a tune capability claim from one BlueField generation to another. Re-read the public matrix per doca-public-knowledge-map ## DOCA tools (doca-public-knowledge-map/SKILL.md#doca-tools).

• Where it runs. The binary runs on the side the operator has DOCA installed (host x86 / Arm, BlueField Arm, or NGC container). The Flow application it observes can be on the same side or — when the documented attach role's IPC reaches across — on the colocated side. What matters is that the tool, the application's linked Flow library, and the install version agree per the four-way match above.

Error taxonomy

doca_flow_tune's error surface is broader than a pure read-only CLI because the tool both observes live state and recommends a change against it; each side has its own failure modes. The error layers the agent should distinguish, in escalating order:

1. Config-syntax. The invocation itself does not parse or the JSON config is malformed: unknown flag, malformed JSON, a network.server_uds path that the operator cannot create, a monitor.hardware.pci_addresses entry the device does not expose, conflicting flags. Cause: the operator wrote a flag or JSON field that does not exist on the installed version (often a field taken from prose / blog / older release). Routing: re-read --help on the installed binary and the configuration-file example in the public DOCA Flow Tune guide; do not guess.

2. Attach-failed (online mode). The invocation parses; the tool cannot reach the live Flow application's tune-server endpoint. Cause: the Flow application is not running, the application's tune-server role was never started, the configured network.server_uds path does not exist or is not writable from the application's process, the application is running but the file-system namespace the socket lives in is not visible from the tool's side (e.g. one is inside a container the other is not). Routing: confirm the Flow application is up via doca-flow TASKS.md ## test (doca-flow/TASKS.md#test); confirm the socket path matches the application's actual network.server_uds value; confirm the namespace boundary.

3. Pipe-not-found. The tool attached, but the pipe the operator named in scope is missing from the snapshot. Cause: the Flow application never created that pipe (route to doca-flow TASKS.md ## modify (doca-flow/TASKS.md#modify)), the pipe was destroyed by a previous program-side action, or the operator is using the wrong identifier. The right move is to confirm the pipe set against the Flow application's own view, not to re-run the tune session expecting different output.

4. Measurement-unsound. The session runs to completion and reports counters / KPIs, but the numbers are unsound and must not be quoted as-is. Three sub-layers:

   • Warm-up / steady-state not reached. The snapshot was taken during a transient state of the live Flow application; the dumper CSV captures cold-cache / cold-pipeline iterations and is below steady-state. Fix: let the application reach steady state before capturing.

   • Outliers / distribution unreported. A single hardware-counter delta hides a heavy tail; a single lookup-latency reading hides a 99.99-percentile spike. Fix: report the distribution alongside any single number per the quote what the tool said rule in ## Safety policy.

   • Before / after pair not captured. The recommendation was applied without a before snapshot; the delta cannot be defended. Fix: re-run with a pre-change snapshot, then the change, then the post-change snapshot.

5. Recommendation-unactionable. The analyze step produced a recommendation, but it does not correspond to a knob the surrounding doca-flow program exposes (the recommendation targets a pipe attribute the program hard-codes, or the recommendation requires a Flow API the program does not call). Cause: the recommendation was generic across the tool's library of known patterns and the program is more constrained than the patterns assume. The right move is the minimum-diff modification workflow in TASKS.md ## modify — surface the recommendation as a Flow-program-change proposal, not as a knob the tune binary itself can flip.

6. Version. Cross-cutting partial-install / mixed-version layer per doca-version CAPABILITIES.md ## Version compatibility (doca-version/CAPABILITIES.md#version-compatibility). Symptoms: tune binary version disagrees with the Flow application's linked Flow library version, the visualize step renders a degenerate diagram on a known-good pipeline layout, the analyze step produces JSON fields the public guide's documented schema does not list. Routing: walk doca-version TASKS.md ## debug (doca-version/TASKS.md#debug) before any further investigation.

7. Cross-cutting. The cause is below DOCA — driver, firmware, BlueField mode, NUMA, hugepages. Symptoms that do not fit layers 1-6 (e.g. counter deltas that fall sharply only on one NUMA node, attach failures correlated with mlx5_core reload, recommendations that do not move the metric even after a clean before / after pair). Routing: hand off to doca-debug ## debug (doca-debug/SKILL.md) and doca-setup ## debug (doca-setup/TASKS.md#debug); the tune surface has reached its limit.

doca_flow_tune does not itself participate in the cross-library DOCA_ERROR_* taxonomy in the way an application- linked library does; the tool is a CLI that drives observation and analysis. For the cross-library DOCA_ERROR_* family and the program-side debug order, see doca-programming-guide CAPABILITIES.md ## Error taxonomy (doca-programming-guide/CAPABILITIES.md#error-taxonomy).

Observability

doca_flow_tune is itself an observability primitive for the rest of the Flow surface — it is what other skills load to see what a Flow pipeline is actually doing without re-instrumenting the Flow program. Specifically:

• Dumper output (JSON or CSV). Per the dumper.file_name field, the tool can write a JSON or CSV file (per format_type / --dump-file-format) of the captured counters / KPIs. The dump file is the documented machine-readable surface — the agent's rule for any baseline that will be re-read by a later run is capture CSV, not just stdout.

• Analyze output (JSON). Per the analyze.file_name field, the tool emits a pipeline-description JSON file that captures the structural and counter view of the pipeline; this is the artifact the visualize step consumes and the artifact a follow-up tune session can replay in offline mode.

• Visualize output (mermaid markdown). Per the visualize.file_name field, the tool renders the pipeline description as a mermaid markdown diagram suitable for a pull-request review or a debug session log.

• Monitor output. Per the monitor.screen_mode field plus the monitor.hardware and monitor.software profile sets, the tool can drive a screen-mode live view of the configured hardware / software profiles (per-pipe operations rates, hardware counters by PCI device, etc.). Useful for a real-time check that a tuning change has taken effect; the CSV dumper is the right surface for a captured baseline.

• Logs. Per the logging.developer_log and logging.operational_log fields, the tool writes a developer- level and an operational-level log; the agent's rule is quote what the log said when diagnosing layer 2 (attach-failed) or layer 4 (measurement-unsound) per ## Error taxonomy.

For the cross-cutting env-side observability primitives (representor enumeration, devlink dev show, mlxconfig) see doca-setup CAPABILITIES.md ## Observability (doca-setup/CAPABILITIES.md#observability). For the program-side observability surface (DOCA_LOG_LEVEL, --sdk-log-level, the trace build flavor) see doca-programming-guide CAPABILITIES.md ## Observability (doca-programming-guide/CAPABILITIES.md#observability). For the Flow library's own programmatic counter / inspector surface see doca-flow CAPABILITIES.md ## Observability (doca-flow/CAPABILITIES.md#observability).

Safety policy

Overlay on the bundle-wide hardware-safety meta-policy. The rules below are this skill's per-artifact overlay on the cross-cutting rules in doca-hardware-safety CAPABILITIES.md ## Safety policy (doca-hardware-safety/CAPABILITIES.md#safety-policy) (specifically ### Per-artifact overlay pattern (doca-hardware-safety/CAPABILITIES.md#per-artifact-overlay-pattern)). When the two layers disagree, the stricter wins; when either layer says STOP, the agent stops.

doca_flow_tune is the most dataplane-sensitive tool this bundle currently teaches an agent to drive directly: a recommended parameter change applied back to the surrounding Flow program lands in live Flow state on a running dataplane. The safety rules:

• Read-only by default; state-changing only after a clean snapshot. The offline mode and the online read-only mode do not touch live Flow state and can be re-run freely. Applying a recommendation back to the Flow program — even via a code change reviewed in a pull request — does change live Flow state on the next deploy, can disrupt in-flight traffic, and is the high-stakes class of operation the agent must call out as such before recommending it.

• Smoke-before-bulk is mandatory. Before any application of a recommendation, the agent runs the snapshot → analyze → visualize → confirm-before-change sequence in TASKS.md ## test. A recommendation applied without that sequence is a guess against possibly-stale evidence — exactly the failure mode this rule exists to prevent.

• Every recommendation requires its own explicit confirmation. Before changing the Flow program, present the exact recommendation, scope, tuning axis, expected measurement direction, minimum diff, and rollback snapshot. Do not treat a prior confirmation as approval for a different recommendation or axis.

• Bound the non-green loop. After a non-green result, reselect exactly one axis and try one newly confirmed recommendation. A second non-green result requires restoring the pre-change snapshot via doca-flow TASKS.md ## rollback (doca-flow/TASKS.md#rollback) and escalating with both captured diffs; do not begin a third attempt.

• Quote the four-tuple, not just the recommendation. A doca_flow_tune recommendation is only meaningful with the (command line + JSON config + DOCA version + device + as-deployed environment) tuple. Quoting "tune said sizing X is better" without the tuple is unfalsifiable.

• Do not invent flags, JSON fields, or recommendation identifiers. The documented surface is the surface; the public DOCA Flow Tune guide plus the installed --help are the joint source of truth. Prose-derived field names are the most common hallucination failure for this skill; see the cross-cutting rule in TASKS.md ## Command appendix.

• Never widen the attach role as a workaround. When the tool cannot read what it expected, walk ## Error taxonomy — do not enable a state-changing access surface, do not bypass a namespace boundary, do not relax filesystem permissions on the network.server_uds socket so the symptom goes away.

Public-source pointer

The single canonical public source for doca_flow_tune is the DOCA Flow Tune page on docs.nvidia.com, reachable through doca-public-knowledge-map ## DOCA tools (doca-public-knowledge-map/SKILL.md#doca-tools). Do not invent flag strings, JSON config field names, recommendation identifiers, or output column names beyond what that page documents — and re-verify against --help on the user's installed binary, since granular-build support means the available surface is install-specific within the documented surface. For the doca-flow API behind the pipeline being tuned, the source of truth is doca-flow/SKILL.md plus the public DOCA Flow guide reached the same way. For the measurement side, see monitor mode in ## Capabilities and modes.