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
  category: datacenter
  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 -- 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
Understand how the pieces fit together Architecture
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
Call it from your own tool Embedding it