CLI Reference

CLI Reference

The shell library covers the common case — see Quick Start. This page is for running the binary directly.

logger-rs \
  --output /g/data/ab12/dashboard/$USER/psutil_$PBS_JOBID.log \
  --interval 0.5

Arguments

Argument	Default	Notes
--output, --outfile	required	NDJSON output path. Supports {host}, {jobid}, {user}. Parent directories are created.
--check	—	Preflight the node and exit. See below.
--merge DIR	—	Merge the per-node summaries in DIR into one job-level summary and exit. Needs --job-id.
--merge-expect-nodes	—	Comma-separated allocation, so the merge can report nodes that never reported.
--write-manifest DIR	—	Write the job manifest and exit. Needs --job-id.
--node-rank	—	This node's index in the allocation.
--summary	<output>.summary.json	Summary JSON path.
--interval	0.5	Sampling interval, seconds. Must be ≥ 0.1.
--gpu-interval	5.0	GPU polling interval. Each poll forks nvidia-smi, so this is deliberately coarser. Must be ≥ --interval.
--tree-pid	parent PID	Root of the process tree to measure.
--procs-from	auto	cgroup, tree or auto. See Architecture.
--cgroup DIR	autodetected	Bypass cgroup discovery entirely.
--exit-status-file	none	File the wrapper writes the workload's exit status to.
--user-id	$USER
--job-id	$PBS_JOBID
--queue, --job-name, --project	from PBS env
--booked-walltime, --booked-mem	from PBS env	Used for efficiency calculations.

Environment variables are read for all of the above; --help lists the exact names.

--check

logger-rs --check

Run inside a short interactive job. Reports the cgroup version and scope, which controllers the job actually owns, whether the output path is writable, where the binary lives and whether other nodes could run it, and what will therefore be missing.

Exit status is deliberately narrow: non-zero only when the run would produce nothing usable. A missing controller costs one metric and is reported as a warning, because a job that measures CPU but not disk is still worth running — failing the check there would train people to ignore it.

Output format

NDJSON — one JSON object per line. Three event types:

• job_start — once at the beginning: identity, booked resources, cgroup version, logger version.
• job_log — every --interval seconds: the metrics in Metrics.
• job_end — once at shutdown: exit status, exit reason, duration, CPU core-seconds and core-hours.

A separate <output>.summary.json is written on exit, and for multi-node jobs a merged psutil_<jobid>.summary.json alongside it. See Multi-Node Jobs and Dashboard Integration for the schema and its stability guarantees.