/doca-ngauge

license: Apache-2.0
name: doca-ngauge
description: >
  Use this skill when the operator is driving the DOCA ngauge tool to
  analyze, visualize, and debug network performance on a single node by
  probing NIC hardware counters and storing collected data in HDF5 format.
  Trigger even when the user does not say "DOCA ngauge" — implicit
  phrasings include "probe NIC hardware counters", "collect HDF5
  performance data", "plot ngauge output", "sample counters on
  BlueField/ConnectX", "measure network performance on a single node",
  "debug network performance with hardware counters", "run ngauge YAML
  config", "parse ngauge HDF5 output". Refuse and route elsewhere:
  DOCA install/bring-up to doca-setup, version questions to
  doca-version, hardware/firmware state changes to doca-hardware-safety,
  raw packet I/O to doca-eth, and host-DPU messaging to doca-comch.
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: tool
  doca_version: "3.5"
  tags:
    - doca
    - ngauge
    - counters
    - hdf5
    - performance
    - telemetry
compatibility: >
  Requires a host with ngauge installed (sudo apt-get install ngauge or
  sudo dnf install ngauge on x86 or Arm 64 hosts; pre-installed on the
  DPU) and a BlueField-3 or ConnectX-7 or above device with firmware
  version xx.43.1000 or higher. The fwctl driver must be installed on the
  host; on Linux kernel 6.15 and above it is available by default unless
  explicitly disabled during kernel configuration. ngauge cannot run
  simultaneously with other tools or services that also use fwctl.

DOCA ngauge

Scope boundaries

These requests are out of scope: say so, name the skill that owns the request, and stop.

• raw Ethernet packet send/receive at line rate: `doca-eth/SKILL.md`.
• host-DPU control-plane messaging (Comch): `doca-comch/SKILL.md`.
• DOCA install and bring-up: `doca-setup/SKILL.md`.
• which DOCA version is installed, version compatibility: `doca-version/SKILL.md`.
• NIC or BlueField mode and firmware changes: `doca-hardware-safety/SKILL.md`.
• general DOCA orientation and documentation lookup: `doca-public-knowledge-map/SKILL.md`.

Examples

• **"Probe NIC hardware counters on a BlueField-3 and save HDF5

data."** — this is in scope. Configure the YAML file and run ngauge; do not attempt to change hardware or firmware state here.

• **"Plot the collected counter data from an ngauge output file."** —

use the sample plugins under `/usr/share/doc/ngauge/examples/plugins`; dependencies may need separate installation.

• **"ngauge cannot start because fwctl is in use."** — check for

other tools or services that also use fwctl; route install and driver conflict resolution to `doca-setup`.

Quick facts

The authoritative source for the binary name, flags, paths, and configuration schema is the public DOCA ngauge guide at https://docs.nvidia.com/doca/archive/3-5-0/doca-ngauge/index.html. Confirm details with the installed tool's `--help` and the sample configuration files before quoting them.

• ngauge analyzes, visualizes, and debugs network performance on a

single node by probing NIC hardware counters and storing collected data in HDF5 format with relevant metadata.

• Supported hardware: NVIDIA BlueField-3, NVIDIA ConnectX-7, and

above; firmware version xx.43.1000 or higher.

• ngauge relies on the fwctl driver and cannot run simultaneously

with other tools or services that also use fwctl.

• All configurations are defined in an input YAML file. Sample

configuration files are under `/usr/share/doc/ngauge/examples/settings`.

• The device is specified by its PCIe address, for example

`device: "0000:03:00.0"`.

• Output path and file prefix are mandatory. The output file is saved

as `/path/to/output/directory/<prefix>_<DATE>_<TIME>.h5`; the exact file name is printed after each run.

• The `silent` option suppresses CLI progress indications when set to

`true` (default `false`).

• Runtime parameters include `mode` (`repetitive` or `single`) and

`period_us` (sampling period in microseconds; decimal or scientific notation accepted, e.g. `1e2` = 100 μs).

• Counter definitions require `id` (data ID); optional fields are

`desc`, `unit`, `accumulating`, `normalizer` (`time`, a non-zero number, or a configured data ID with an `id/` prefix), `cutoff_min`, and `cutoff_max`.

• All supported performance counters are listed in the public guide's

"Supported Data IDs" section.

• Run ngauge with:

  ngauge <configuration YAML file>

• To end a run early, use Ctrl+C (SIGINT). This is a normal and

supported way to stop; all results collected up to that point are saved as usual.

• During a run, progress bars for each counter are displayed. Color

coding: blue for low values, red for high values, gradient for intermediate values, solid gray for no changes. Data is updated once per second, showing mean, standard deviation (σ), minimum, and maximum observed during the last second.

• To reference the most recent results when the output directory is

`/tmp` (the default), use:

  $(ls -1 /tmp/ngauge_data_*.h5 | tail -n1)

Instructions

Follow Loading order below. Open the tasks companion for configure / run / parse / debug. Open the capabilities companion for what ngauge measures and reports. Do not open every companion file.

**Where to start:** This is a tool skill for invoking DOCA ngauge — the single-node network performance analysis, visualization, and debugging tool that probes NIC hardware counters and stores HDF5 data. Open the tasks companion and start at `## configure` for the YAML configuration decision, then `## run` for the execution flow. Open the capabilities companion when the question is *what counters can be measured, what metadata is stored, and what the progress display implies*. If the user has not installed ngauge or fwctl, route to `doca-setup/SKILL.md` first. If the user is asking about hardware/firmware state changes, route to `do