/doca-flow-perf

license: Apache-2.0
name: doca-flow-perf
description: >
  Use this skill when the user is measuring the host or DPU-CPU
  control-plane rate of a DOCA Flow pipeline with doca_flow_perf —
  picking a JSON policy from configs/, choosing the DPDK or DOCA
  backend, running the single-iteration smoke then the iterative eval
  loop, interpreting per-iteration CPU cycles and num_pushed /
  num_failed, or capturing the four-tuple (DOCA version,
  BlueField/firmware, JSON policy, worker/queue/burst config) that
  makes a Kops/sec number defensible. Trigger even when the user does
  not explicitly mention "doca-flow-perf" — typical implicit phrasings
  include "how many rules per second can my BlueField insert",
  "5-tuple hairpin rule rate", "Kops/sec for steering", "flow-perf
  number does not match release notes", "DPDK vs DOCA benchmark", or
  "rule-install variance too high". Refuse and route elsewhere for
  optimizing a live Flow app (doca-flow-tune), the DPA-offloaded path
  (doca-flow-dpa-perf), dataplane throughput or latency, or
  library-internal pipe semantics — those belong to other skills.
metadata:
  kind: tool
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. The doca_flow_perf binary plus its configs/ JSON exemplars
  must be present (the DOCA Flow Perf install component), with the
  underlying doca-flow library healthy. Reads `pkg-config doca-flow`
  and inspects /opt/mellanox/doca/{lib,include,samples,applications}.

DOCA Flow Perf (`doca_flow_perf`)

**Where to start:** This is a tool skill for invoking `doca_flow_perf`, the host-side / DPU-CPU-side DOCA Flow performance measurement tool. Open [`TASKS.md`](TASKS.md) and start at [`## configure`](TASKS.md#configure) to commit to the three-axis decision (target Flow pipeline shape × traffic class × measurement axis) and pick the JSON policy file that expresses the workload, then [`## run`](TASKS.md#run) for the single-iteration smoke, then [`## test`](TASKS.md#test) for the iterative eval loop that produces a defensible Kops/sec-class number. Open [`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what `doca_flow_perf` measures and what it deliberately does not measure*, *how its DPDK and DOCA backends differ behind the same JSON contract*, *how to interpret the per-iteration CPU-cycle output*, or *how it differs from `doca-flow-tune` (measurement vs. optimization) and `doca-flow-dpa-perf` (host / DPU-CPU vs. DPA-offloaded path)*. If DOCA is not installed, route to [`doca-setup`](../../doca-setup/SKILL.md) first; if the target measurement is the DPA-offloaded path, route to [`doca-flow-dpa-perf`](../doca-flow-dpa-perf/SKILL.md) instead; if the goal is to optimize an already-deployed Flow pipeline rather than measure a synthetic one, route to [`doca-flow-tune`](../doca-flow-tune/SKILL.md) — `flow-perf` is a synthetic-driver microbenchmark, not a tuner of a live Flow application.

Example questions this skill answers well

• *"I want a defensible host-side baseline number for how

many `doca-flow` rules per second a single BlueField-3 can insert for a 5-tuple match-and-hairpin workload. Which policy JSON do I start from, how do I make the result reproducible, and what do I have to capture alongside the number for it to be defensible?"* — class-shaped flow-perf baseline question; the agent walks the `configs/` library, the JSON contract, and the four-tuple capture rule.

• *"What is the difference between `doca-flow-perf`,

`doca-flow-dpa-perf`, and `doca-flow-tune`? They all mention `doca-flow` and `perf` in their names — when do I reach for each?"* — measurement-vs-optimization plus host-vs-DPA-path; the agent surfaces the boundaries.

• *"My policy JSON looks like the example, but the reported

Kops/sec is dramatically lower than the published numbers I see in NVIDIA's release notes. What variables do I have to control before I can trust the comparison?"* — methodology question; the agent walks the controllable axes (number of workers, queue depth, burst size, fixed-vs-incremented match fields, DPDK vs DOCA backend, BlueField mode, driver / firmware).

• *"I have a workload that does not match any of the shipped

policy JSONs in `configs/`. How do I author a new policy JSON, what is the JSON schema in broad strokes, and what changes when I switch a match field from `mode: fixed` to `mode: increase`?"* — JSON authoring question; the agent walks the shipped configs as exemplars and refuses to invent schema fields not present in the source tree.

• *"What does the tool actually NOT measure? I am trying to

understand whether a flow-perf number tells me anything about end-to-end traffic latency or just about the rule-programming control-plane rate."* — methodology perimeter question; the agent draws a hard line: this tool measures rule install / delete (control-plane) rate plus optional query rate, NOT dataplane latency, NOT dataplane throughput, NOT end-to-end application performance.

• *"I see two backends — DPDK and DOCA — behind the same

JSON. When do I pick which, and what does the choice mean for the result I report?"* — backend choice question; the agent walks the DPDK-backend vs. DOCA-backend trade-off and insists the operator REPORT which one they used.

Audience

Experienced AI agents and platform / network engineers who are comfortable with the `doca-flow` programming model and the DPDK control-plane, who want a *defensible* number for the host-side / DPU-CPU-side Flow rule-install / rule-delete rate. Readers are expected to know that the published numbers in NVIDIA release notes are run with very specific preconditions (specific DOCA version, specific BlueField firmware, specific traffic class) and that any number they produce locally must explicitly state those preconditions.

This skill is NOT for:

• operators who want to o