Tracking

substrax.tracking records scalars, images, histograms, text and hyperparameters per step, to the console, to files, to Weights & Biases or to MLflow, behind one Logger interface.

from substrax.tracking import FileLogger, WandbLogger

logger = FileLogger("run-1", log_dir="logs/run-1")
logger.log_scalars({"loss": 0.42, "accuracy": 0.9}, step=100)
logger.log_image("samples", images, step=100)
logger.log_hyperparams({"learning_rate": 1e-3})
logger.close()

wandb_logger = WandbLogger("run-1", project="my-project")

Backend	Extra	Where things go
ConsoleLogger	none	logging lines on stdout
FileLogger	plots for figures	Lines to a .log file, scalars to a long-form CSV (timestamp,step,name,value), images and histograms to PNGs, texts and hyperparameters to text files
WandbLogger	wandb	A W&B run; log_code and log_model upload code and model artifacts
MLFlowLogger	mlflow, plots for figures	An MLflow run; images, histograms and texts as run artifacts

Importing substrax.tracking imports neither SDK. A backend loads its SDK when constructed and raises ImportError naming the extra to install:

uv add 'substrax[wandb]'

substrax.tracking

Step-wise experiment tracking with console, file, Weights & Biases and MLflow backends.

Importing this package imports neither wandb nor mlflow; each backend loads its SDK when constructed and raises ImportError naming the extra that provides it.

ConsoleLogger(name, log_dir=None, level=logging.INFO)

Bases: Logger

Logger that writes lines to the console only.

log_scalars(scalars, step=None)

Log several scalars as one line.

log_image(name, image, step=None)

Log the image count or shape, not the pixels.

log_histogram(name, values, step=None)

Log the summary statistics of values, not the histogram.

log_text(name, text, step=None)

Log text under name.

log_hyperparams(params)

Log one line per hyperparameter.

FileLogger(name, log_dir, filename=None, level=logging.INFO)

Bases: ConsoleLogger

Logger that writes the console lines to a file as well.

Scalars also go to <name>_<timestamp>_metrics.csv (one timestamp, step, name, value row per scalar), images to images/, histograms to histograms/, texts to texts/ and hyperparameters to hyperparams_<timestamp>.txt. Images and histograms need the plots extra; without it they are logged as lines only.

Initialise the file logger.

Parameters:

Name	Type	Description	Default
name	str	Name of the logger.	required
log_dir	str | Path	Directory to save logs to.	required
filename	str | None	Log filename. None derives one from name and the time.	None
level	int	Logging level.	INFO

log_scalars(scalars, step=None)

Log several scalars as one line and append them to the metrics CSV.

log_image(name, image, step=None)

Log the image and save it under images/.

log_histogram(name, values, step=None)

Log the summary statistics and save the histogram under histograms/.

log_text(name, text, step=None)

Log text and save it under texts/.

log_hyperparams(params)

Log the hyperparameters and save them to hyperparams_<timestamp>.txt.

Logger(name, log_dir=None, level=logging.INFO)

Bases: ABC

Base class for all loggers.

Concrete loggers record scalars, images, histograms, text and hyperparameters somewhere; every logger also owns a :mod:logging logger named after it whose handlers it replaces, so lines reach stdout exactly once.

Initialise the logger.

Parameters:

Name	Type	Description	Default
name	str	Name of the logger and of its :mod:logging logger.	required
log_dir	str | Path | None	Directory for files, created if missing. None writes no files.	None
level	int	Logging level from the :mod:logging module.	INFO

log(msg, level=logging.INFO)

Log a message at level.

debug(msg)

Log a debug message.

info(msg)

Log an info message.

warning(msg)

Log a warning message.

error(msg)

Log an error message.

critical(msg)

Log a critical message.

log_scalar(name, value, step=None)

Log one scalar; the default records it through :meth:log_scalars.

Parameters:

Name	Type	Description	Default
name	str	Name of the scalar.	required
value	float	Scalar value to log.	required
step	int | None	Global step value to record, for example the training iteration.	None

log_scalars(scalars, step=None) abstractmethod

Log several scalars.

Parameters:

Name	Type	Description	Default
scalars	Mapping[str, float]	Scalar names to values.	required
step	int | None	Global step value to record.	None

log_image(name, image, step=None) abstractmethod

Log an image or a list of images.

Parameters:

Name	Type	Description	Default
name	str	Name of the image.	required
image	ArrayLike | Sequence[ArrayLike]	One array of shape (H, W) or (H, W, C), or a list of them.	required
step	int | None	Global step value to record.	None

log_histogram(name, values, step=None) abstractmethod

Log a histogram of values.

Parameters:

Name	Type	Description	Default
name	str	Name of the histogram.	required
values	ArrayLike | Sequence[float]	Values to build the histogram from.	required
step	int | None	Global step value to record.	None

log_text(name, text, step=None) abstractmethod

Log text.

Parameters:

Name	Type	Description	Default
name	str	Name of the text entry.	required
text	str	Text to log.	required
step	int | None	Global step value to record.	None

log_hyperparams(params) abstractmethod

Log hyperparameters.

Parameters:

Name	Type	Description	Default
params	Mapping[str, object]	Hyperparameter names to values.	required

close()

Close the logger's handlers and release their resources.

MLFlowLogger(name, *, log_dir=None, experiment_name=None, run_name=None, run_id=None, tracking_uri=None, registry_uri=None, level=logging.INFO)

Bases: Logger

Logger that records metrics, parameters and artifacts in an MLflow run.

Images, histograms and texts are written to <log_dir>/artifacts/<kind>/ when a log directory is given, else to a temporary file, and logged as run artifacts under <kind>. Images and histograms need the plots extra.

Start or resume the MLflow run.

Parameters:

Name	Type	Description	Default
name	str	Name of the logger; also the experiment name when none is given.	required
log_dir	str | Path | None	Local directory for artifacts, in addition to the run.	None
experiment_name	str | None	MLflow experiment, created if missing.	None
run_name	str | None	Name for a new run. MLflow generates one when omitted.	None
run_id	str | None	An existing run to continue; experiment_name and run_name are then ignored.	None
tracking_uri	str | None	MLflow tracking server. None keeps the environment's.	None
registry_uri	str | None	MLflow model registry. None keeps the tracking URI.	None
level	int	Logging level.	INFO

Constructing the logger raises ImportError when the mlflow extra is not installed.

log_scalar(name, value, step=None)

Log one metric.

log_scalars(scalars, step=None)

Log several metrics.

log_image(name, image, step=None)

Log an image or a list of images as an artifact under images.

log_histogram(name, values, step=None)

Log the summary statistics as metrics and the histogram as an artifact.

log_text(name, text, step=None)

Log text as an artifact under texts.

log_hyperparams(params)

Log the hyperparameters as run parameters.

MLflow accepts strings, numbers and booleans; anything else is logged as its str representation.

log_artifact(local_path, artifact_path=None)

Log one file as a run artifact.

Parameters:

Name	Type	Description	Default
local_path	str | Path	File to log.	required
artifact_path	str | None	Directory within the run's artifacts to place it in.	None

log_artifacts(local_dir, artifact_path=None)

Log every file in a directory as run artifacts.

Parameters:

Name	Type	Description	Default
local_dir	str | Path	Directory whose files to log.	required
artifact_path	str | None	Directory within the run's artifacts to place them in.	None

end_run()

End the run; a second call is a no-op.

close()

End the run and close the logger.

WandbLogger(name, project, *, entity=None, log_dir=None, config=None, tags=None, notes=None, level=logging.INFO, **init_options)

Bases: Logger

Logger that records metrics, media and artifacts in a Weights & Biases run.

Start the W&B run.

Parameters:

Name	Type	Description	Default
name	str	Name of the run and of the logger.	required
project	str	Name of the W&B project.	required
entity	str | None	User or team that owns the project.	None
log_dir	str | Path | None	Local directory for W&B's own files, in addition to the run.	None
config	Mapping[str, object] | None	Hyperparameters to record on the run.	None
tags	Sequence[str] | None	Tags for the run.	None
notes	str | None	Notes about the run.	None
level	int	Logging level.	INFO
**init_options	Any	Further keyword arguments for wandb.init, such as mode="offline" or resume="allow"; the SDK owns their meaning.	{}

Constructing the logger raises ImportError when the wandb extra is not installed.

log_scalars(scalars, step=None)

Log several scalars to the run.

log_image(name, image, step=None)

Log an image or a list of images to the run.

log_histogram(name, values, step=None)

Log the histogram and its summary statistics (<name>/min and so on).

log_text(name, text, step=None)

Log text as a preformatted HTML block.

log_hyperparams(params)

Record the hyperparameters on the run's config.

log_code(root=None)

Save the code under root (default: the current directory) to the run.

log_model(model_path, name=None, metadata=None)

Upload a model file or directory as a W&B artifact of type model.

Parameters:

Name	Type	Description	Default
model_path	str | Path	File or directory to upload.	required
name	str | None	Artifact name; defaults to <run name>_model.	None
metadata	Mapping[str, object] | None	Metadata to record on the artifact.	None

finish(exit_code=0)

Finish the run; a second call is a no-op.

Parameters:

Name	Type	Description	Default
exit_code	int	Exit code to report to W&B.	0

close()

Finish the run and close the logger.

create_logger(name, log_dir=None, *, log_to_file=True, level=logging.INFO)

Create a console logger, or a file logger that also logs to the console.

Parameters:

Name	Type	Description	Default
name	str	Name of the logger.	required
log_dir	str | Path | None	Directory to save logs to. None with log_to_file means ./logs/<name>.	None
log_to_file	bool	Whether to write files as well as console lines.	True
level	int	Logging level.	INFO

Returns:

Name	Type	Description
A	Logger	class:FileLogger when log_to_file is set, else a :class:ConsoleLogger.