Run logging

Run records connect training results to the configuration and data choices that produced them. RunLogger writes events to metrics.jsonl and displays progress in the terminal. The engine supplies execution details and metrics; the workflow supplies the scientific context of the run.

Configuration and events

Pass scientific configuration through trainer.train(..., metadata={...}) and configure RunLogger to persist UTC-stamped events. Each started/resumed call records the execution configuration, budget, world size, precision, optimizer groups, EMA, objective coefficients and supplied metadata. Workflows supply units, normalization, data splits, seeds, and the concrete scheduler recipe.

Train metrics report per-group lr/0, lr/1, etc. used by the most recent attempted update, pre-clipping grad_norm averaged over successful updates, actual last_update_samples, and samples_per_second excluding evaluation and checkpoint phases. Evaluation records raw/EMA selection and duration; checkpoint records the chosen position and best/final flags; export records the weight choice and path. Finished/stopped events summarize per-call train, evaluation, and checkpoint wall time. These diagnostic timings are not a substitute for controlled performance benchmarks.

Use RunLogger as a context manager, as in the training example, to close its event file and terminal display when the run ends. Pass is_main_process=accelerator.is_main_process so one process writes the shared run records.

Logging API

RunLogger(run_dir: Path, *, is_main_process: bool, console: Console | None = None)

log(event: Mapping[str, Any]) -> None

close() -> None