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 optimize an already-deployed
  `doca-flow` application — that is
  [`doca-flow-tune`](../doca-flow-tune/SKILL.md);
- operators measuring the DPA-offloaded Flow path — that is
  [`doca-flow-dpa-perf`](../doca-flow-dpa-perf/SKILL.md);
- operators measuring end-to-end dataplane throughput or
  latency — that is the application's responsibility,
  layered on
  [`doca-flow`](../../libs/doca-flow/SKILL.md);
- contributors authoring or modifying the tool itself.

## Language scope

User interaction with `doca_flow_perf` is via:

1. The shipped binary's command-line flags (documented by
   `doca_flow_perf --help` and the public DOCA Flow Perf
   guide on `docs.nvidia.com`).
2. A JSON policy file describing the pipeline (ports, pipes,
   matchers, actions, forwarding). The shipped `configs/`
   directory contains canned policies for the most common
   traffic classes; new policies are authored by copying and
   editing one of those.
3. The tool's per-iteration output (CPU cycles per iteration,
   number-processed, number-failed; reported via the tool's
   stdout — the exact format is the public guide and the
   binary's runtime output, NOT this skill's invention).

The skill itself is Markdown. There is no programmatic API on
top of `doca_flow_perf`; consumers of its results read its
stdout / captured logs.

## When to load this skill

Load `doca-flow-perf` when ANY of the following is true:

- the user mentions `doca_flow_perf`, `doca-flow-perf`, the
  `configs/` JSON library, or asks for a "host-side flow
  rules per second" number;
- the user wants to baseline an underlying Flow path (not
  optimize a live application);
- the user is comparing host-side / DPU-CPU-side Flow
  performance across DOCA releases, BlueField generations,
  or firmware versions;
- the user wants to design a new traffic class JSON and
  needs to know which canned `configs/` JSON to start from
  and which fields they can change.

Co-load this skill with:

- [`doca-flow`](../../libs/doca-flow/SKILL.md) (the
  underlying library; flow-perf programs the same
  matchers / actions / pipes the library exposes);
- [`doca-flow-tune`](../doca-flow-tune/SKILL.md) (the
  measurement-vs-optimization distinction is the most
  common confusion);
- [`doca-flow-dpa-perf`](../doca-flow-dpa-perf/SKILL.md)
  (the host-vs-DPA-path distinction is the second most
  common confusion);
- [`doca-version`](../../doca-version/SKILL.md) (the
  four-way version match every reported flow-perf number
  must carry);
- [`doca-debug`](../../doca-debug/SKILL.md) and
  [`doca-setup`](../../doca-setup/SKILL.md) for the
  env-side debug ladder.

Do NOT load this skill when the user wants to optimize a live
Flow application (route to
[`doca-flow-tune`](../doca-flow-tune/SKILL.md)) or measure
the DPA-offloaded path (route to
[`doca-flow-dpa-perf`](../doca-flow-dpa-perf/SKILL.md)).

## What this skill provides

Three companion files in this directory, each owning a
different question shape:

- [`SKILL.md`](SKILL.md) — this file. Audience, scope,
  loading order, related skills. Routes everything else.
- [`CAPABILITIES.md`](CAPABILITIES.md) — *what
  `doca_flow_perf` is*, what it measures, what it
  deliberately doesn't measure, the DPDK-vs-DOCA backend
  duality, the JSON contract surface, the per-iteration
  output interpretation, version compatibility (versioned
  with `doca-flow` and `doca-version`), the layered error
  taxonomy, observability, and the safety policy overlay.
- [`TASKS.md`](TASKS.md) — the procedural verbs (`configure`,
  `run`, `test`, `debug`, etc.) plus a `doca_flow_perf`-
  specific command appendix and the agent-side `use`
  workflow that consumes the captured per-iteration output.

The combined skill teaches an AI agent to drive the
*measurement-class* of `doca_flow_perf` questions: pick a
shipped or author-new policy JSON, run the single-iteration
smoke, run the iterative eval loop, capture the four-tuple
that makes the resulting number defensible, interpret the
output, and route every adjacent question (tune the live
app, measure the DPA path, optimize the firmware) to the
right neighbouring skill.

## What this skill deliberately does not ship

- **End-to-end dataplane throughput or latency
  measurement.** `doca_flow_perf` measures the
  *control-plane* rate of programming rules, plus optional
  per-entry query timing. It does NOT measure how fast
  packets traverse the resulting rules in the dataplane.
  That is the application's responsibility, layered on
  [`doca-flow`](../../libs/doca-flow/SKILL.md). The agent
  must say this explicitly when the operator asks for "Flow
  throughput".
- **DPA-offloaded Flow path measurement.** Route to
  [`doca-flow-dpa-perf`](../doca-flow-dpa-perf/SKILL.md).
- **Optimization of a deployed Flow application.** Route to
  [`doca-flow-tune`](../doca-flow-tune/SKILL.md). flow-perf
  is a synthetic driver of a JSON-described pipeline, not a
  tuner of a live one.
- **A canonical "right answer" Kops/sec number.** The agent
  refuses to quote published numbers from memory as
  authoritative; the published numbers live in NVIDIA's
  release notes per the DOCA version and BlueField
  generation, and the operator must reproduce on their own
  exact preconditions before comparing.
- **Invented JSON schema fields.** The agent does NOT invent
  policy JSON keys that are not present in the shipped
  `configs/` exemplars. If a key the operator wants is not
  in any shipped exemplar, the agent says so and routes to
  the public DOCA Flow Perf guide.
- **Library-internal `doca-flow` API explanations.** The
  underlying matchers and actions belong to
  [`doca-flow`](../../libs/doca-flow/SKILL.md); this skill
  references them but does not duplicate the library's API
  documentation.
- **Cross-tool benchmarking apples-to-apples claims** when
  preconditions differ. Two flow-perf numbers from different
  DOCA versions / BlueField generations / firmware versions
  are NOT directly comparable; the agent insists on the
  four-tuple capture so consumers can judge.

## Loading order

When a `doca_flow_perf` question arrives:

1. Confirm DOCA is installed and the binary plus the
   `configs/` JSON library are reachable — if not, route to
   [`doca-setup`](../../doca-setup/SKILL.md);
2. Confirm the underlying `doca-flow` library is healthy on
   the device — if not, route to
   [`doca-flow TASKS.md ## test`](../../libs/doca-flow/TASKS.md#test);
3. Confirm the user wants to *measure*, not *optimize* —
   if optimize, route to
   [`doca-flow-tune`](../doca-flow-tune/SKILL.md);
4. Confirm the target path is host / DPU-CPU, not DPA — if
   DPA, route to
   [`doca-flow-dpa-perf`](../doca-flow-dpa-perf/SKILL.md);
5. Read [`CAPABILITIES.md`](CAPABILITIES.md) to commit to
   the three-axis decision (pipeline shape × traffic class ×
   measurement axis);
6. Read [`TASKS.md`](TASKS.md) and walk
   `## configure → ## run → ## test → ## debug` in that
   order; do NOT start with `## run` without the
   `## configure` precondition step.

## Related skills

Cross-link conventions follow the bundle's relative path
contract from `tools/<X>/`:

- [`doca-flow`](../../libs/doca-flow/SKILL.md) — the
  underlying library. flow-perf programs Flow pipes, entries,
  matchers, and actions; the library is the source of truth
  for the API surface flow-perf exercises.
- [`doca-flow-tune`](../doca-flow-tune/SKILL.md) — the
  unified Flow tuning tool. **Measurement vs. optimization
  boundary** lives here. Ask: "do I want a number, or do I
  want to change the deployed pipeline?"
- [`doca-flow-dpa-perf`](../doca-flow-dpa-perf/SKILL.md) —
  the DPA-offloaded Flow performance tool. **Host /
  DPU-CPU vs. DPA path boundary** lives here. Ask: "am I
  measuring the path that executes on the CPU, or the path
  that executes on the DPA processor?"
- [`doca-version`](../../doca-version/SKILL.md) — every
  reported flow-perf number must come with the four-way
  match (host package, kernel module, firmware, target
  application's linked `doca-flow` version) and the BlueField
  / ConnectX generation. flow-perf overlays this rule, not
  contradicts it.
- [`doca-setup`](../../doca-setup/SKILL.md) — DOCA install
  posture; routing for "is the binary even here?" questions.
- [`doca-debug`](../../doca-debug/SKILL.md) — the
  cross-cutting debug ladder for env-side issues (driver,
  firmware, BlueField mode, kernel module).
- [`doca-bench`](../doca-bench/SKILL.md) — a peer
  benchmarking tool with a broader scope (multiple DOCA
  primitives, not just Flow). flow-perf is the Flow-specific
  microbenchmark; doca-bench is the broader workload
  benchmark.
- [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md)
  — routing to the public `docs.nvidia.com` DOCA Flow Perf
  page, release notes, and forums for release-specific
  published numbers and reproducibility notes.
- [`doca-structured-tools-contract`](../../doca-structured-tools-contract/SKILL.md)
  — the agent's detect → prefer → fall back → report contract
  for the structured helpers (`doca-env --json`,
  `doca-capability-snapshot`, `version-matrix.json`)
  flow-perf preconditions rely on.
- [`doca-hardware-safety`](../../doca-hardware-safety/SKILL.md)
  — the canonical hardware-safety meta-policy that
  [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
  overlays.

This skill assumes the surrounding doca-flow application is
the operator's existing source artifact; flow-perf does not
ship a sample doca-flow application of its own.