Skip to content

mlperf-sysinfo

A tool that automatically captures the system description of a benchmarking machine, built on top of the mlc-scripts and mlcflow automation.

Install

pip install mlperf-sysinfo

Quick Run

The steps below capture a system description for a CPU-only system, using only the machine you run them on. No other node is contacted.

Step 1 -- create a starter config

mlperf-sysinfo init endpoints
Sample output 
$ mlperf-sysinfo init endpoints
[2026-08-19 21:37:29] INFO     init: wrote template sysinfo.yaml (profile endpoints) to /home/user/sysinfo.yaml
[2026-08-19 21:37:29] INFO     init: edit it before running 'mlperf-sysinfo capture -c sysinfo.yaml'

Step 2 -- edit sysinfo.yaml

The sample below is a complete config for a CPU-only capture of the machine you're on.

See The endpoints config for every option this profile reads.

profile: endpoints

output:
  dir: results/sysinfo

system:
  name: devbox1
  shortened_name: devbox1
  availability: available
  accelerator: none

nodes:
  include_local: true
  ssh: []

serving:
  url: http://127.0.0.1:8000

submission:
  division: standardized

Step 3 -- check the config

mlperf-sysinfo check -c sysinfo.yaml
Sample output 
$ mlperf-sysinfo check -c sysinfo.yaml

  profile    endpoints
  output     results/sysinfo/system_desc.json

NODES
  ✓ this machine            included

SERVING
  ! http://127.0.0.1:8000   no answer   no serving framework answered

REQUIRED BY PROFILE 'ENDPOINTS'
  ✓ 5 fields set

WORTH FILLING IN
  ! system.cooling              empty   Reviewers ask how the nodes are cooled
  ! serving.node                empty   Enables parallelism and batch settings to be read from the startup log
  ! submission.notes.hardware   empty   Hardware detail no probe can report, such as interconnect topology or firmware
  ! submission.notes.software   empty   Software detail no probe can report, such as versions, flags or patches
  ! run.link_config             empty   Reviewers use it to reproduce the run

[2026-08-19 21:39:59] INFO     check: ready to capture

The warnings above are expected for a config with no live endpoint, and they don't block anything. capture always runs this check first, and there is no flag to skip it; a missing required field or an unreachable node is what would stop the run.

Step 4 -- capture

mlperf-sysinfo capture -c sysinfo.yaml
Sample output 
$ mlperf-sysinfo capture -c sysinfo.yaml
[2026-08-19 21:42:12] INFO     collector: pre-flight check passed -- 1 node(s), profile endpoints
[2026-08-19 21:42:12] INFO     collector: collecting with tags: get-mlperf-multi-node-system-info,_cuda,_endpoints
[2026-08-19 21:42:18] INFO     collector: 1 of 1 node(s) returned hardware
[2026-08-19 21:42:18] INFO     collector: wrote results/sysinfo/system_desc.json
[2026-08-19 21:42:18] INFO     capture: 1 node(s) - 1 accelerators - profile endpoints
[2026-08-19 21:42:18] INFO     capture: run log results/sysinfo/.mlperf-sysinfo/capture_20260819_214212.log
[2026-08-19 21:42:18] INFO     capture: next: mlperf-sysinfo show results/sysinfo/system_desc.json

Step 5 -- validate

mlperf-sysinfo validate results/sysinfo/system_desc.json
Sample output 
$ mlperf-sysinfo validate results/sysinfo/system_desc.json

  file       results/sysinfo/system_desc.json
  profile    endpoints

WARNINGS
  ! cooling on every node type is empty -- Reviewers ask how the nodes are cooled
  ! hw_notes on every node type is empty -- Hardware detail no probe can report, such as interconnect topology or firmware
  ! sw_notes on every node type is empty -- Software detail no probe can report, such as versions, flags or patches
  ! link_config is empty -- Reviewers use it to reproduce the run

[2026-08-19 21:42:30] INFO     report: valid -- 5 required field(s) present, 4 warning(s)

Three rules worth knowing

  • Anything detectable is never a config field

    CPU, memory, accelerators, node counts and framework version are probed. If they appear in your config at all, they are overrides.

  • Required means required

    A field a profile needs and cannot detect must be filled in. A config still saying CHANGEME is not filled in, and the checker says so.

  • ${VAR} reads from the environment

    BMC and API credentials are referenced, never written into the file, never committed.

Where to go next

If you want to… Read
Write or fix a config The config file
Look up a command or an exit code Commands
See what a real capture produces Sample outputs
Understand how the pieces fit together Architecture