doca-flow-perf

# DOCA Flow Perf (`doca_flow_perf`) ## Examples - **"How many rules per second can my BlueField insert?"** — this is in scope. Stay on `doca_flow_perf`; do not retune a live Flow app here. - **"DPDK vs DOCA benchmark."** — pick the JSON policy and backend; capture the four-tuple that makes Kops/sec defensible. - **"My production pipeline is losing hardware offload."** — out of scope: that is diagnosing a live Flow application, owned by `doca-flow-tune`. Name it and stop; do not run a `doca_flow_perf` benchmark for it. ## Instructions Follow Loading order below. Open the tasks companion for configure / run / debug. Open the capabilities companion for backends and policy files. Do not open every companion file. **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 the tasks companion 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 the capabilities companion 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. **How to use this skill.** Read this file, then search the companion file for the `## <name>` heading the question needs and read that whole section. Answer completely from it, quoting only its symbols and commands. Do not browse docs; use the entry points in `doca-public-knowledge-map`. Give environment checks as commands for the user's DOCA host. For out-of-scope requests, name the skill that owns them and stop. ## 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: - this skill — this file. Audience, scope, loading order, related skills. Routes everything else. - the capabilities companion — *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. - the tasks companion — 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`](../../libs/doca-flow/SKILL.md); 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 the capabilities companion to commit to the three-axis decision (pipeline shape × traffic class × measurement axis); 6. Read the tasks companion 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 the capabilities companion 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.