/doca-bench

license: Apache-2.0
name: doca-bench
description: >
  Run `doca_bench` (DOCA 2.7.0 or newer) to measure throughput,
  bulk latency, precision latency, or maximum bandwidth for RDMA,
  Compress, AES-GCM, SHA, DMA, EC, Ethernet, Comch, or GPUNetIO on
  a host or BlueField Arm. Use it to discover enabled benchmark
  libraries, capture a reproducible command/version/device/environment
  baseline, compare stable runs against a declared tolerance, or
  diagnose configuration, device-binding, workload-precondition, and
  measurement failures. Trigger for requests such as measuring
  BlueField compression speed, NIC RDMA throughput, crypto latency,
  or a pre-upgrade baseline. Do not use for application end-to-end
  timing, custom benchmark code, DOCA installation, or binary patches.
metadata:
  kind: tool
compatibility: >
  Requires DOCA SDK ≥ 2.7.0 installed at /opt/mellanox/doca on
  Linux (Ubuntu 22.04/24.04 or RHEL/SLES) with a BlueField DPU or
  ConnectX NIC attached and the `doca_bench` binary present at
  /opt/mellanox/doca/tools/doca_bench. Companion app must run on
  the far side for remote-memory / RDMA / Eth scenarios; host and
  BlueField-Arm execution both supported.

DOCA Bench (`doca_bench`)

**Where to start:** This is a tool skill for invoking `doca_bench`, the cross-library micro-benchmark harness. Open [`TASKS.md`](TASKS.md) and start at [`## configure`](TASKS.md#configure) for the three-axis decision (target library × workload shape × measurement axis), then [`## run`](TASKS.md#run) for the smoke-before-bulk flow. Open [`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what `doca_bench` can measure*, *which DOCA libraries it can drive*, or *how to interpret throughput / latency / op-rate output without fooling yourself on warm-up or steady-state*. If DOCA is not installed yet, route to [`doca-setup`](../../doca-setup/SKILL.md) first; if the install version is < 2.7.0, `doca_bench` is not shipped on this host.

Example questions this skill answers well

The CLASSES of `doca_bench` 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.

• **"What does this DOCA library actually deliver on this device?"** —

worked example: *"throughput of DOCA Compress on my BlueField-3"*. Answered by the three-axis configuration in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the smoke-before-bulk flow in

[`TASKS.md ## run`](TASKS.md#run). The *same* shape answers *"send-side throughput of DOCA RDMA"* — `doca_bench` is cross-library, not single-library.

• **"Which DOCA libraries can `doca_bench` actually drive on this

install?"** — worked example: *"is doca_sha enumerable on a granular-build install"*. Answered by the built-in query system surfaced in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• [`TASKS.md ## configure`](TASKS.md#configure) step 2

(probe-before-bench). Empty enumeration = library not installed, not bench failure.

• **"Is this number reliable, or did I miss the warm-up?"** —

worked example: *"why does my first-second number differ from my steady-state number"*. Answered by the measurement-soundness overlay in [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy) layer 5 + [`TASKS.md ## test`](TASKS.md#test) (the eval-loop overlay treats warm-up / steady-state / outliers as re-iteration triggers, not one-shot facts).

• **"Bench reports zero throughput / hangs at start / disagrees

with the public docs."** — worked example: *"`doca_bench` shows zero ops for AES-GCM but `doca_caps` says the device supports it"*. Answered by the layered error taxonomy in [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy) (config-syntax → device-binding → library-precondition → workload-precondition → measurement-soundness → version → cross-cutting) + [`TASKS.md ## debug`](TASKS.md#debug).

• **"How do I capture a baseline I can later regression-test

against?"** — worked example: *"snapshot decompress throughput on this BlueField + DOCA version before a firmware update"*. Answered by the CSV output + version-overlay rule in [`TASKS.md ## test`](TASKS.md#test) (capture command line + version + device + as-deployed environment alongside the numbers; quoting numbers without the four-tuple is the cross-version regression-hunt failure mode).

• **"`doca_bench` returns nothing for library X — what does that

mean?"** — worked example: *"empty output for DOCA SHA"*. Answered by the empty-output interpretation rules in [`TASKS.md ## debug`](TASKS.md#debug) + [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy). Re-route through [`doca-caps`](../doca-caps/SKILL.md) for the coarse per-device per-library capability ground truth, then back into bench once the capability is confirmed present.

Audience

This skill serves **external operators, developers, and AI agents who need a reproducible, vendor-supported way to measure DOCA library performance on the user's actual install and device**. Concretely:

• An external developer choosing between DOCA libraries (e.g.

COMPRESS vs SHA vs DMA throughput) before committing an application design.

• A platform operator validating a tuning change (NUMA pinning,

driver upgrade, firmware burn) by re-running a captured `doca_bench` baseline against the new state.

• An SRE / performance engineer producing a *"this is what the

device delivers today"* artifact that downstream consumers (capacity planning, regression bisection) can cite.

• An AI agent answering *"what throughput / latency should I

expect from DOCA library X on device Y?"* honestly — with a measured number, the command line that produced it, and the version + device + environment that scopes it — instead of guessing from datasheet headlines.

It is **not** for users