Skip to content

Experiment loggers

All backends implement the same hyperparameter, scalar metric, artifact, and finalization contract. LoggerCollection broadcasts identical events to each configured backend.

Logger construction does not open files, import optional SDKs, or start remote runs. The Trainer creates logger resources when a task starts and releases them when it ends. Calling a built-in logger directly remains convenient: its first logging operation calls setup() automatically.

Configure logging

Trainer(logger=True) enables local logging by default. It uses TensorBoardLogger when TensorBoard is installed and falls back to CSVLogger otherwise. Runs are stored below <default_root_dir>/phijax_logs/version_N/, including hparams.yaml and scalar metrics. Set logger=False or logger=None to disable logging, or pass one logger or an iterable of loggers explicitly.

trainer = Trainer(max_steps=10_000, default_root_dir="outputs")

Inspect TensorBoard runs with:

tensorboard --logdir outputs/phijax_logs

Loggers expose name, version, and log_dir. Progress callbacks display the primary version as v_num; subclasses may remove it by overriding get_metrics() and popping that key. Local and remote logging is owned by global rank zero.

Pass a plain mapping to Trainer.fit() to record run settings before the first update:

result = trainer.fit(
    module,
    datamodule=data_module,
    optimizer=optimizer,
    seed=0,
    hyperparameters={"model": {"width": 64}, "seed": 0},
)

Hydra projects can convert their composed config with to_hyperparameters() before passing it to fit(). The Trainer performs the logger call after rank and task setup, so entrypoints do not need a separate logging utility.

Modules may select destinations with self.log() during on_train_batch_end(). This records device values without writing them immediately. The Trainer exposes three read-only views of the same latest metric store:

  • callback_metrics contains every module and callback value, including arrays;
  • logged_metrics contains scalar values selected for experiment loggers;
  • progress_bar_metrics contains scalar values selected for terminal display.

Logger conversion still follows log_every_n_steps. Progress callbacks transfer their selected values only at their own refresh interval.

Logger contracts

ExperimentLogger [source]

Define the minimal interface shared by experiment-logging backends.

Logger constructors must not create files, start remote runs, or acquire other external resources. Resource acquisition belongs in the idempotent :meth:setup hook, and :meth:finalize must tolerate calls before setup and repeated calls after cleanup.

name property 

name: str

Return the logger or experiment name.

Returns:

Type Description
str

Stable logger name.

version property 

version: int | str | None

Return the experiment version when available.

Returns:

Type Description
int | str | None

Integer or string version, or None for unversioned loggers.

log_dir property 

log_dir: Path | None

Return the local run directory when available.

Returns:

Type Description
Path | None

Local run directory, or None for remote or stream loggers.

setup [source] 

setup() -> None

Prepare task-local logger resources idempotently.

log_hyperparams [source] 

log_hyperparams(parameters: Mapping[str, Any]) -> None

Record resolved experiment parameters.

Parameters:

Name Type Description Default
parameters Mapping[str, Any]

Resolved scalar or nested experiment configuration.

 required

log_metrics [source] 

log_metrics(
    metrics: Mapping[str, float], step: int
) -> None

Record scalar metrics for one optimizer step.

Parameters:

Name Type Description Default
metrics Mapping[str, float]

Host scalar metric mapping.

 required
step int

Optimizer step associated with metrics.

 required

Raises:

Type Description
RuntimeError

If TensorBoard does not create an event writer.

log_artifact [source] 

log_artifact(path: str | Path) -> None

Record or register an experiment artifact.

Parameters:

Name Type Description Default
path str | Path

Existing local artifact path.

 required

finalize [source] 

finalize(status: str) -> None

Flush resources and record the terminal run status.

Parameters:

Name Type Description Default
status str

Terminal status such as success or failed.

 required

LoggerCollection [source] 

LoggerCollection(loggers: Iterable[ExperimentLogger] = ())

Bases: ExperimentLogger

Fan each logging operation out to multiple independent backends.

Initialize a logger fan-out collection.

Parameters:

Name Type Description Default
loggers Iterable[ExperimentLogger]

Logging backends receiving every operation.

 ()

name property 

name: str

Return the primary logger name.

Returns:

Type Description
str

First backend name, or this collection's class name when empty.

version property 

version: int | str | None

Return the primary logger version.

Returns:

Type Description
int | str | None

First backend version, or None when empty.

log_dir property 

log_dir: Path | None

Return the primary local log directory.

Returns:

Type Description
Path | None

First backend log directory, or None when empty.

__bool__ [source] 

__bool__() -> bool

Return whether the collection contains a configured backend.

Returns:

Type Description
bool

Whether at least one logger is configured.

setup [source] 

setup() -> None

Prepare every configured backend for a new task.

log_hyperparams [source] 

log_hyperparams(parameters: Mapping[str, Any]) -> None

Forward hyperparameters to all backends.

Parameters:

Name Type Description Default
parameters Mapping[str, Any]

Resolved experiment configuration.

 required

log_metrics [source] 

log_metrics(
    metrics: Mapping[str, float], step: int
) -> None

Forward scalar metrics to all backends.

Parameters:

Name Type Description Default
metrics Mapping[str, float]

Host scalar metric mapping.

 required
step int

Optimizer step associated with metrics.

 required

log_artifact [source] 

log_artifact(path: str | Path) -> None

Forward one artifact to all backends.

Parameters:

Name Type Description Default
path str | Path

Existing local artifact path.

 required

finalize [source] 

finalize(status: str) -> None

Finalize every backend.

Parameters:

Name Type Description Default
status str

Terminal run status.

 required

Local loggers

Console

ConsoleLogger writes scalar updates to the terminal without creating a run directory.

ConsoleLogger [source] 

ConsoleLogger(
    name: str = "phijax.training", level: int = logging.INFO
)

Bases: ExperimentLogger

Write compact scalar training progress through PhiJAX's color logger.

Initialize console logging.

Parameters:

Name Type Description Default
name str

Python logger name.

 'phijax.training'
level int

Standard-library logging level.

 INFO

log_hyperparams [source] 

log_hyperparams(parameters: Mapping[str, Any]) -> None

Log the number of resolved top-level parameters.

Parameters:

Name Type Description Default
parameters Mapping[str, Any]

Resolved experiment configuration.

 required

log_metrics [source] 

log_metrics(
    metrics: Mapping[str, float], step: int
) -> None

Log one compact, deterministically ordered metric line.

Parameters:

Name Type Description Default
metrics Mapping[str, float]

Host scalar metric mapping.

 required
step int

Optimizer step associated with metrics.

 required

log_artifact [source] 

log_artifact(path: str | Path) -> None

Log the local artifact path.

Parameters:

Name Type Description Default
path str | Path

Existing local artifact path.

 required

finalize [source] 

finalize(status: str) -> None

Log the terminal run status.

Parameters:

Name Type Description Default
status str

Terminal run status.

 required

CSV

CSVLogger writes hyperparameters and scalar history into a local versioned run directory.

CSVLogger [source] 

CSVLogger(
    save_dir: str | Path,
    filename: str = "metrics.csv",
    *,
    name: str = "csv",
    version: int | str | None = None,
)

Bases: ExperimentLogger

Append dynamically named scalar metrics to a long-form CSV file.

Attributes:

Name Type Description
path

Destination CSV path.

Initialize a long-form CSV logger.

Parameters:

Name Type Description Default
save_dir str | Path

Directory containing the metrics file.

 required
filename str

CSV filename within save_dir.

 'metrics.csv'
name str

Logger or experiment name.

 'csv'
version int | str | None

Optional run version displayed by progress callbacks.

 None

name property 

name: str

Return the experiment name.

Returns:

Type Description
str

Configured experiment name.

version property 

version: int | str | None

Return the experiment version.

Returns:

Type Description
int | str | None

Configured version.

log_dir property 

log_dir: Path

Return the local run directory.

Returns:

Type Description
Path

Directory containing metrics and hyperparameters.

setup [source] 

setup() -> None

Open the CSV stream for a new task when it is currently closed.

log_hyperparams [source] 

log_hyperparams(parameters: Mapping[str, Any]) -> None

Write resolved parameters to hparams.yaml.

Parameters:

Name Type Description Default
parameters Mapping[str, Any]

Resolved experiment configuration.

 required

log_metrics [source] 

log_metrics(
    metrics: Mapping[str, float], step: int
) -> None

Append one row per scalar metric.

Parameters:

Name Type Description Default
metrics Mapping[str, float]

Host scalar metric mapping.

 required
step int

Optimizer step associated with metrics.

 required

log_artifact [source] 

log_artifact(path: str | Path) -> None

Ignore artifacts because CSV has no artifact store.

Parameters:

Name Type Description Default
path str | Path

Existing local artifact path.

 required

finalize [source] 

finalize(status: str) -> None

Flush and close the metrics file.

Parameters:

Name Type Description Default
status str

Terminal run status, unused by this backend.

 required

TensorBoard

TensorBoardLogger writes event files that can be inspected with TensorBoard.

TensorBoardLogger [source] 

TensorBoardLogger(
    save_dir: str | Path,
    *,
    name: str = "tensorboard",
    version: int | str | None = None,
)

Bases: ExperimentLogger

Write scalar summaries using TensorBoard's dependency-light event writer.

Initialize TensorBoard event logging.

Parameters:

Name Type Description Default
save_dir str | Path

Directory receiving TensorBoard event files.

 required
name str

Logger or experiment name.

 'tensorboard'
version int | str | None

Optional run version displayed by progress callbacks.

 None

name property 

name: str

Return the experiment name.

Returns:

Type Description
str

Configured experiment name.

version property 

version: int | str | None

Return the experiment version.

Returns:

Type Description
int | str | None

Configured version.

log_dir property 

log_dir: Path

Return the TensorBoard run directory.

Returns:

Type Description
Path

Directory containing event files and hyperparameters.

setup [source] 

setup() -> None

Create a TensorBoard writer for a new task when needed.

Raises:

Type Description
ModuleNotFoundError

If the optional tensorboard extra is not installed.

log_hyperparams [source] 

log_hyperparams(parameters: Mapping[str, Any]) -> None

Write resolved parameters to hparams.yaml.

Parameters:

Name Type Description Default
parameters Mapping[str, Any]

Resolved experiment configuration.

 required

log_metrics [source] 

log_metrics(
    metrics: Mapping[str, float], step: int
) -> None

Write scalar TensorBoard summaries.

Parameters:

Name Type Description Default
metrics Mapping[str, float]

Host scalar metric mapping.

 required
step int

Optimizer step associated with metrics.

 required

log_artifact [source] 

log_artifact(path: str | Path) -> None

Ignore artifacts because the scalar writer has no artifact store.

Parameters:

Name Type Description Default
path str | Path

Existing local artifact path.

 required

finalize [source] 

finalize(status: str) -> None

Flush and close the TensorBoard event writer.

Parameters:

Name Type Description Default
status str

Terminal run status, unused by this backend.

 required

Remote loggers

Weights & Biases

WandbLogger starts its run lazily and uploads metrics, hyperparameters, and configured artifacts.

WandbLogger [source] 

WandbLogger(
    project: str,
    *,
    save_dir: str | Path | None = None,
    entity: str | None = None,
    name: str | None = None,
    run_id: str | None = None,
    group: str | None = None,
    job_type: str | None = None,
    tags: Sequence[str] = (),
    mode: str | None = None,
    resume: str | bool | None = None,
    artifact_type: str = "model",
    init_kwargs: Mapping[str, Any] | None = None,
)

Bases: ExperimentLogger

Log experiments through the optional Weights & Biases SDK.

The owned W&B run is finalized idempotently by :meth:finalize. When constructed inside :func:task_wrapper, the logger also registers the same finalizer as a failure-safe for errors outside :meth:Trainer.fit.

Attributes:

Name Type Description
run Any

Lazily initialized W&B run returned by wandb.init().

Initialize one W&B run without making the SDK a core dependency.

Parameters:

Name Type Description Default
project str

W&B project name.

 required
save_dir str | Path | None

Local directory for W&B run files.

 None
entity str | None

Optional W&B team or account name.

 None
name str | None

Optional human-readable run name.

 None
run_id str | None

Optional stable run identifier used for resumption.

 None
group str | None

Optional run group.

 None
job_type str | None

Optional job-type label.

 None
tags Sequence[str]

Optional run tags.

 ()
mode str | None

W&B mode such as online, offline, or disabled.

 None
resume str | bool | None

W&B resume policy. When omitted with run_id, defaults to allow.

 None
artifact_type str

Default type assigned to logged artifact paths.

 'model'
init_kwargs Mapping[str, Any] | None

Additional keyword arguments forwarded to wandb.init().

 None

run property 

run: Any

Return the active W&B run, starting it on first access.

Returns:

Type Description
Any

Active W&B run returned by wandb.init().

name property 

name: str

Return the W&B project name.

Returns:

Type Description
str

Configured project name.

version property 

version: str | None

Return the configured W&B run identifier.

Returns:

Type Description
str | None

Stable run identifier, or None when W&B generated it.

log_dir property 

log_dir: Path | None

Return the local W&B storage directory.

Returns:

Type Description
Path | None

Configured local directory, or None.

setup [source] 

setup() -> None

Start the configured W&B run when it is not already active.

Raises:

Type Description
ModuleNotFoundError

If the optional wandb extra is not installed.
RuntimeError

If wandb.init() does not return a run.

log_hyperparams [source] 

log_hyperparams(parameters: Mapping[str, Any]) -> None

Update the W&B run configuration.

Parameters:

Name Type Description Default
parameters Mapping[str, Any]

Resolved experiment configuration.

 required

log_metrics [source] 

log_metrics(
    metrics: Mapping[str, float], step: int
) -> None

Log one scalar metric mapping at an explicit monotonically increasing step.

Parameters:

Name Type Description Default
metrics Mapping[str, float]

Host scalar metric mapping.

 required
step int

Training step associated with metrics.

 required

log_artifact [source] 

log_artifact(path: str | Path) -> None

Upload a local file or directory as a versioned W&B artifact.

Parameters:

Name Type Description Default
path str | Path

Existing local artifact path.

 required

finalize [source] 

finalize(status: str) -> None

Flush pending W&B data and finish the run exactly once.

Parameters:

Name Type Description Default
status str

Terminal run status; only success maps to exit code 0.

 required

Optional dependencies

uv sync --extra tensorboard
uv sync --extra cuda13 --extra wandb

W&B authenticates through wandb login or the WANDB_API_KEY environment variable. Do not interpolate credentials into project configuration because resolved configurations are commonly printed and saved.

WANDB_API_KEY="your-key" python -m my_project.train logger=wandb

Root tags are forwarded to compatible loggers:

python -m my_project.train logger=wandb tags='[baseline,gpu]'

Custom logger lifecycle

A custom ExperimentLogger should follow three rules:

  • Keep __init__() free of filesystem, network, and optional-dependency side effects.
  • Create resources in an idempotent setup() method.
  • Make finalize() safe before setup, after partial setup, and when called more than once.

Only global rank zero calls setup, logging methods, artifact methods, and finalization. Logger objects are still constructed on every rank so callbacks see the same has_logger value.