doca-flow-tune

Files (8)

• BENCHMARK.md
• CAPABILITIES.md
• SKILL.md
• SKILLCARD.yaml
• TASKS.md
• evals.json · evals/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

# 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-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

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills