Doca Flow Perf

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 and start at ## 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 for the single-iteration smoke, then ## test for the iterative eval loop that produces a defensible Kops/sec-class number. Open 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 first; if the target measurement is the DPA-offloaded path, route to doca-flow-dpa-perf instead; if the goal is to optimize an already-deployed Flow pipeline rather than measure a synthetic one, route to doca-flow-tune — 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;
• operators measuring the DPA-offloaded Flow path — that is doca-flow-dpa-perf;
• operators measuring end-to-end dataplane throughput or latency — that is the application's responsibility, layered on doca-flow;
• 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 (the underlying library; flow-perf programs the same matchers / actions / pipes the library exposes);
• doca-flow-tune (the measurement-vs-optimization distinction is the most common confusion);
• doca-flow-dpa-perf (the host-vs-DPA-path distinction is the second most common confusion);
• doca-version (the four-way version match every reported flow-perf number must carry);
• doca-debug and doca-setup 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) or measure the DPA-offloaded path (route to doca-flow-dpa-perf).

What this skill provides

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

• SKILL.md — this file. Audience, scope, loading order, related skills. Routes everything else.
• 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 — 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.