Skip to main content
skill CX Codex

doca-bench — Claude Code skill: benchmarks and setup

This skill guides doca_bench runs to measure DOCA library performance on a host or BlueField Arm. Use it to check throughput or latency and record a baseline before changing a system.

Apache-2.0 166 installs ★ 4,106 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add NVIDIA/skills --skill doca-bench -a claude-code
Open on GitHub

What doca-bench does

doca_bench measures throughput, bulk and precision latency, and maximum bandwidth for RDMA, Compress, AES-GCM, SHA, DMA, EC, Ethernet, Comch, and GPUNetIO. The skill helps select a library, workload shape, and measurement axis, then run a test and investigate configuration, device-binding, or workload issues.

You can capture a baseline with the command, DOCA version, device, and environment, then compare a later run against a declared tolerance. Remote-memory, RDMA, and Ethernet scenarios need a companion app running on the far side.

The host needs Linux, DOCA SDK 2.7.0 or newer, a BlueField DPU or ConnectX NIC, and the doca_bench binary. Without a live DOCA installation, the validation steps cannot run. This skill does not cover end-to-end application timing or custom benchmark code.

What it helps with

  • measure a DOCA library’s throughput on a device
  • check AES-GCM or RDMA latency
  • record a baseline before a firmware update
  • investigate zero-throughput benchmark results

Example prompts for the agent

  • Measure DOCA Compress throughput on this BlueField.
  • Record RDMA baseline results before the firmware update, including the command, version, device, and environment.
  • Find out why doca_bench reports zero throughput for AES-GCM.

How to install doca-bench

1Skills CLI (Vercel)

npx skills add NVIDIA/skills --skill doca-bench -a claude-code

2Manually: put the files in place

~/.claude/skills/doca-bench/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/doca-bench/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about doca-bench

How do I install doca-bench in Claude Code?

Run npx skills add NVIDIA/skills --skill doca-bench -a claude-code. The skill file is located at ~/.claude/skills/doca-bench/SKILL.md.

What does doca-bench do?

It guides doca_bench runs that measure throughput, latency, and maximum bandwidth for DOCA libraries. It also helps capture results for later comparison and troubleshoot run failures.

What do I need to run doca-bench?

You need Linux with DOCA SDK 2.7.0 or newer, a BlueField DPU or ConnectX NIC, and the doca_bench binary. Remote-memory, RDMA, and Ethernet scenarios require a companion app on the far side.

Source text

SKILL.md · Apache-2.0
---
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:
  author: NVIDIA <[email protected]>
  kind: tool
  doca_version: "3.5"
  tags:
    - doca
    - bench
    - perf
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. The validation steps require a live DOCA
  install.
---

# DOCA Bench (`doca_bench`)

## Examples

- **"What does this DOCA library actually deliver on this device?"** —
  this is in scope. Stay on `doca_bench`; do not write a custom
  microbenchmark.
- **"Which DOCA libraries can `doca_bench` drive on this install?"** —
  probe the built-in query first; empty enumeration is a missing
  library, not a bench failure.

## Instructions

Follow Loading order below. Open the tasks companion for configure /
run / debug. Open the capabilities companion for modes and
measurement soundness. Do not open every companion file.

**Where to start:** This is a tool skill for invoking `doca_bench`,
the cross-library micro-benchmark harness. Open
the tasks companion and start at
`## configure` for the three-axis decision
(target library × workload shape × measurement axis), then
`## run` for the smoke-before-bulk flow. Open
the capabilities companion 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/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
  the capabilities companion
  + the smoke-before-bulk flow in
  the tasks companion. 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
  the capabilities companion
  + the tasks companion 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
  the capabilities companion
  layer 5 + the tasks companion (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
  the capabilities companion
  (config-syntax → device-binding → library-precondition →
  workload-precondition → measurement-soundness → version →
  cross-cutting) + the tasks companion.
- **"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
  the tasks companion (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
  the tasks companion +
  the capabilities companion.
  Re-route through
  `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 debugging the `doca_bench` source code,
and **not** a substitute for the live public DOCA Bench guide on
`docs.nvidia.com`.

`doca_bench` is shipped as a **tool** (a single CLI binary plus a
companion app for the remote half of remote-memory / RDMA / Eth
scenarios), not a library you link against. The skill uses the
same `kind: tool` three-file shape as the rest of the bundle so
the agent's task-verb contract
(`configure / build / modify / run / test / debug`) is uniform
across libraries, services, and tools — even when individual
verbs collapse to a routing stub for a shipped binary.

## When to load this skill

Load this skill when the user is — or the agent needs to — invoke
`doca_bench` on a real host with DOCA ≥ 2.7.0 installed (or
inside the public NGC DOCA container with the equivalent version)
to measure performance of a DOCA library. Concretely:

- Picking *which* DOCA library to benchmark for a candidate
  workload (RDMA vs COMPRESS vs DMA, etc.).
- Picking *which* measurement axis to ask for (throughput vs bulk
  latency vs precision latency) — the three modes the public guide
  documents; confirm the list with `--help`. The modes are not interchangeable.
- Probing the install's granular-build state so the agent can
  honestly report *"this library is not exposed on this install"*
  instead of inventing a workload.
- Capturing a documented baseline (command line + version + device
  + as-deployed environment + numbers) for later regression hunts.
- Requiring the workload owner to predeclare acceptable variance
  and obtaining two consecutive runs within that tolerance before
  reporting a stable result; otherwise escalating the variance.
- Diagnosing why a bench run reported zero / unstable / unexpected
  results (the error-taxonomy walk in
  the tasks companion).

Do **not** load this skill for general DOCA orientation, library
API work, or installation. For those, use
`doca-public-knowledge-map/SKILL.md`,
the matching `libs/<library>` skill, or
`doca-setup/SKILL.md`. Do not load it for
*application-level* end-to-end benchmarking either — `doca_bench`
measures the DOCA library surface, not the user's application
above it.

## What this skill provides

This is a **thin loader**. Substantive material lives in two
companion files:

- the capabilities companion — what `doca_bench` can measure (the
  cross-library scope, the three-axis configuration model, the
  documented operating modes, the warm-up / pipeline / multi-core
  concepts that constrain measurement soundness), the version
  overlay (`doca-bench`-specific facts on top of the canonical
  `doca-version` rules), the layered error taxonomy
  (config-syntax / device-binding / library-precondition /
  workload-precondition / measurement-soundness / version /
  cross-cutting), the observability surface (screen + CSV
  output, real-time stats, query system), and the safety
  posture (the public guide's *"not for production"* warning,
  the host vs BlueField execution rule, the companion-app
  attack surface).
- the tasks companion — step-by-step workflows for the in-scope task
  verbs: `configure` (the three-axis decision + the
  probe-before-bench step), `build` (route to install — the
  binary is shipped, the companion app is shipped), `modify`
  (refuse — do not patch the bench binary; modify the bench
  *invocation* instead), `run` (the smoke-before-bulk flow),
  `test` (the eval loop — warm-up, steady-state, outliers,
  cross-version), `debug` (walk the error taxonomy layer by
  layer), plus a `Deferred task verbs` block routing
  out-of-scope questions and a `Command appendix` of
  `doca_bench`-specific invocation classes.

The skill assumes a host where DOCA ≥ 2.7.0 is already installed
(or the public NGC DOCA container is running at an equivalent
version) and the operator has whatever permissions the public
guide requires for `doca_bench` to bind devices and allocate
resources on their platform.

## What this skill deliberately does not ship

This skill is **agent guidance**, not a samples or scripts
bundle. To keep the boundary clean, it deliberately does not
contain — and pull requests should not add:

- **Specific flag strings or scenario / metric / attribute names
  beyond what the public DOCA Bench guide documents.** The flag
  surface evolves and is install-specific; the documented
  invocations + `--help` on the installed version are the
  authoritative answer. Inventing a flag is the most common
  hallucination failure for this skill.
- **Pre-baked example output or expected throughput numbers.**
  Bench output is device-, version-, firmware-, NUMA-, and
  tuning-specific. A captured number pinned to one platform and
  one DOCA version misleads operators on a different
  platform / version.
- **Wrappers, parsers, or scripts** in any language that consume
  `doca_bench` CSV or stdout. The output formats are documented;
  if a user wants to script against them, the right answer is
  "read the live guide, write the parser against your installed
  version".
- **A `samples/` or `reference/` subtree.** This is a thin
  loader for a documented CLI; substantive material lives on
  the public page and in `--help`.

## Loading order

1. Read this skill first to confirm the user's question is
   in scope (the user actually wants to invoke `doca_bench` for
   measurement, not learn about a DOCA library in general).
2. **For what `doca_bench` measures, the three-axis model, the
   version overlay, the error taxonomy, observability surface,
   and safety posture, see the capabilities companion.**
3. **For the documented invocations and the smoke-before-bulk
   workflow — `configure`, `build`, `modify`, `run`, `test`,
   `debug` — see the tasks companion.**

## Related skills

- `doca-public-knowledge-map/SKILL.md`
  — routing to the public DOCA Bench page on `docs.nvidia.com`
  and the rest of the public DOCA documentation set.
- `doca-version/SKILL.md` — the canonical
  version-detection chain, four-way match rule, NGC container
  semantics, and headers-win-over-docs rule. The
  `## Version compatibility` section in this skill is a thin
  overlay on top of `doca-version`; the body lives there.
- `doca-structured-tools-contract/SKILL.md`
  — the bundle-wide contract for structured-output helper tools.
  When a site provides a helper that satisfies the
  detect-prefer-fallback-report loop, the `## Command appendix`
  in the tasks companion uses it; otherwise it falls back to the
  manual commands.
- `doca-setup/SKILL.md` — env preparation,
  install verification, hugepages, NUMA awareness, and the *I
  have no install yet* path with the public NGC DOCA container.
- `doca-debug/SKILL.md` — the cross-cutting
  debug ladder. Bench surfaces *its own* error taxonomy in
  the capabilities companion;
  when the cause turns out to be below DOCA (driver, firmware,
  NUMA), the bench taxonomy hands off to `doca-debug`.
- `doca-caps/SKILL.md` — the sibling DOCA tool
  for the coarse per-device per-library capability snapshot.
  Bench probes capability at finer grain via its own query
  system; `doca_caps` is the cheaper first step to confirm the
  device is even visible to DOCA.
- The matching `libs/<library>` skill — e.g.
  `doca-comch/SKILL.md`,
  `doca-compress/SKILL.md` — for
  the workload-side preconditions, capability-query rules, and
  error-taxonomy overlays of the library under test. Bench
  drives the library; the library skill explains *what
  "healthy" means for it*.

© NVIDIA · Apache-2.0 · NVIDIA/skills

Similar skills

All skills for Testing and QA →

From the same set312

The whole set →
nemo-relay-instrument-typed-wrappers nemo-relay-instrument-typed-wrappers configures NeMo Relay typed wrappers and provider codecs while keeping JSON middleware semantics intact. CX Codex +1 182installs nemo-relay-plugin-build nemo-relay-plugin-build is a skill for packaging reusable NeMo Relay behavior as config components or dynamic plugins, with validation and rollback for plugins shared across apps or teams. CX Codex +1 181installs nemo-relay-plugin-adaptive-tuning nemo-relay-plugin-adaptive-tuning is a Claude Code skill that configures and evaluates NeMo Relay adaptive behavior from runtime signals, including telemetry, parallelism, hints, and prompt-cache planning. CX Codex +1 178installs nemo-relay-migrate-from-flow nemo-relay-migrate-from-flow — a skill that automates code, documentation, and config migration from NeMo Flow to NeMo Relay. Handles Python, Rust, Node.js, Go, C FFI, CLI, and observability surfaces. CX Codex +1 171installs nemo-relay-get-started The nemo-relay-get-started skill routes first-time NeMo Relay users to the right quick-start, then checks whether the initial integration actually works. CX Codex +1 163installs doca-debug doca-debug finds the failing DOCA layer, from installation and linking to runtime and drivers. Use it for unresolved symbols, DOCAERROR results, silent tools, and crashes. CX Codex +1 162installs doca-bf3-deployment doca-bf3-deployment is a skill for day-1 BlueField-3 provisioning over classic RShim/BFB, handling BFB image push, TMFIFO setup, DPU mode selection, and recovery. CX Codex +1 159installs doca-bare-metal-deployment doca-bare-metal-deployment is a Claude Code skill for running DOCA applications on an x86 host with a BlueField NIC or on BlueField Arm without containers, and diagnosing launch failures. CX Codex +1 158installs

Project sponsors

Companies that keep this analytics open