/doca-flow-tune

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 writing the doca-flow
  application, DOCA install, or streaming Flow telemetry — those belong
  to other skills.
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: tool
  doca_version: "3.5"
  tags:
    - doca
    - flow
    - tune
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 installed `/opt/mellanox/doca/tools/doca_flow_tune`. The validation steps require a live DOCA
  install.

DOCA Flow Tune (`doca_flow_tune`)

Examples

• **"Flow rule-install rate is low on BlueField."** — this is

in scope. Capture a monitor-mode baseline, then pick one tuning axis.

• **"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); use only the commands the public guide and the > installed `--help` list. > 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 > JSON configuration file; `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.

• **"Do I measure first or tune first?"** — 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"*. Answered by the *measure, then tune* rule in the capabilities companion: a monitor-mode baseline, one tuning axis, then a monitor-mode re-capture on the same axis.

• **"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-s