doca-bench

Measure DOCA library throughput, latency, and bandwidth with the doca_bench CLI harness.

3.2k|370|Updated Feb 25, 2026
One-click install
npx skills add https://github.com/NVIDIA/skills --skill doca-bench
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: doca-bench
Source: https://github.com/NVIDIA/skills/tree/main/skills/doca-bench
Command: npx skills add https://github.com/NVIDIA/skills --skill doca-bench

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Measuring the real performance of NVIDIA DOCA libraries (RDMA, Compress, AES-GCM, SHA, DMA, EC, Ethernet, Comch, GPUNetIO) on a specific host or BlueField Arm device is error-prone: agents and operators guess numbers from datasheets, invent non-existent CLI flags, skip warm-up, and quote results without the version/device context needed to reproduce them. This Skill guides an agent through the shipped doca_bench micro-benchmark harness so measurements are configured, executed, and reported correctly.

Core Features & Use Cases

  • Three-axis benchmark configuration: Pick the target DOCA library, workload shape (direction, data provider, batching, NUMA placement), and measurement mode (throughput, bulk-latency, precision-latency, max-bandwidth) before running anything.
  • Smoke-before-bulk workflow: Run a trivial short workload first to confirm device binding and pipeline startup, then plan sweeps or long runs with a predeclared tolerance and two consecutive stable runs.
  • Layered failure diagnosis: Walk a seven-layer error taxonomy (config-syntax, device-binding, library-precondition, workload-precondition, measurement-soundness, version, cross-cutting) when bench reports zero, hangs, or disagrees with documentation.
  • Use Case: Before a firmware upgrade on a BlueField-3, capture a CSV baseline of DOCA Compress decompress throughput with the full command line, DOCA version, device, and environment, then re-run after the upgrade to regression-test the delta.

Quick Start

Ask your agent to measure the throughput of DOCA Compress on your BlueField device using doca_bench and capture a reproducible baseline.

Frequently Asked Questions about doca-bench

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I benchmark DOCA library performance with doca_bench?

Use doca_bench by committing to three axes: the target DOCA library, the workload shape (direction, data provider, batching, NUMA placement), and the measurement mode (throughput, bulk-latency, precision-latency, or max-bandwidth). Always run a short smoke test before any long or swept run.

What measurement modes does doca_bench support?

doca_bench ships four benchmark modes: throughput (aggregate op-rate), bulk-latency (batched latency distribution), precision-latency (per-job percentiles), and max-bandwidth (saturation ceiling). The modes are not interchangeable, so numbers from different modes must not be compared directly.

Which DOCA version is required for doca_bench?

doca_bench is available since DOCA 2.7.0 and ships at /opt/mellanox/doca/tools/doca_bench on every install, host or BlueField Arm. On older installs the binary is absent, so the fix is upgrading DOCA rather than using alternative tools.

Why does doca_bench report zero throughput or hang?

Zero or hung runs usually come from device-binding or library-precondition failures, not measurement issues. Confirm the device is visible to DOCA with doca_caps, then re-run the bench query system to verify the granular build actually exposes the target library.

Can doca_bench measure application end-to-end latency?

No. doca_bench measures the DOCA library surface only, not application-level end-to-end timing. For application measurements, write a custom program against the relevant DOCA library using the doca-programming-guide and per-library skills.

How do I capture a reproducible doca_bench baseline?

Capture the CSV output plus the four-tuple: exact command line, DOCA version, device target, and as-deployed environment (firmware, kernel, NUMA, hugepages). Require two consecutive runs within a predeclared tolerance before calling the baseline stable.