LogManager

chronax.log_manager.LogManager

Unified logging utility for orchestration, status messages, and TensorBoard logging.

This logger provides: - Standard Python logging to console and/or file - TensorBoard logging for metrics, plots, and hyperparameters - Independent control over each logging type

This class implements a singleton pattern where the first instance created is stored in LogManager.log_manager, and subsequent instantiations return the same instance.

__init__(self, logs_path, name='Tempus Bench', enable_logging=True, console_logging=True, file_logging=True, console_log_level='INFO', file_log_level='DEBUG', tf_logs_path=None, tensorboard_logging=False, verbose=False)

Initialize logger with configuration for both standard and TensorBoard logging.

Note: Logger and SummaryWriter objects are always created regardless of flag values. The actual logging behavior is controlled by enable_logging and tensorboard_logging.

Note: This method only initializes the logger on the first call. Subsequent instantiations will return the same instance without re-initialization.

Parameter	Type	Default	Description
logs_path	str	-	Directory to write standard log files
name	str	'Tempus Bench'	Name for the logger instance
enable_logging	bool	True	Controls whether standard logging methods actually log (Logger is always created)
console_logging	bool	True	Whether to create console handler
file_logging	bool	True	Whether to create file handler
console_log_level	str	'INFO'	Console logging level (DEBUG, INFO, WARNING, ERROR)
file_log_level	str	'DEBUG'	File logging level (DEBUG, INFO, WARNING, ERROR)
tf_logs_path	Optional[str]	None	Directory to write TensorBoard log files (optional, defaults to logs_path/tensorboard)
tensorboard_logging	bool	False	Controls whether TensorBoard logging methods actually log (SummaryWriter is always created)
verbose	bool	False	(undocumented)

get_logger()

Get the LogManager singleton instance.

Parameters: (none) Returns: LogManager (The singleton LogManager instance.) Raises: RuntimeError (If LogManager has not been initialized yet.)

reset_singleton(cls)

Close and clear the singleton so a new run can open different log files.

Long-lived worker processes (e.g. multiple benchmark plan steps) must call this after each :class:~tempus_bench.run_benchmark.BenchmarkRunner exits; otherwise later runs would keep using the first run's handlers and paths.

Parameters: (none) Returns: None.

info(self, module, message, is_verbose=False)

Log an informational message with module context.

Parameter	Type	Default	Description
module	str	-	Module name for context.
message	str	-	Message to log.
is_verbose	bool	False	(undocumented)

warning(self, module, message)

Log a warning message with module context.

Parameter	Type	Default	Description
module	str	-	Module name for context.
message	str	-	Message to log.

error(self, module, message)

Log an error message with module context.

Parameter	Type	Default	Description
module	str	-	Module name for context.
message	str	-	Message to log.

success(self, module, message)

Log a success message with module context.

Parameter	Type	Default	Description
module	str	-	Module name for context.
message	str	-	Message to log.

debug(self, module, message)

Log a debug message with module context.

Parameter	Type	Default	Description
module	str	-	Module name for context.
message	str	-	Message to log.

progress(self, module, message)

Log a progress message with module context.

Parameter	Type	Default	Description
module	str	-	Module name for context.
message	str	-	Message to log.

log_metrics(self, metrics, step, model_name='')

Log evaluation metrics to TensorBoard.

This method logs metrics to TensorBoard, handling various metric value types including scalars, arrays, and nested dictionaries. NaN values are skipped.

Parameter	Type	Default	Description
metrics	dict	-	Dictionary of metrics to log. Values may be scalars, arrays, or nested dictionaries.
step	int	-	The current step (e.g., epoch, batch, or experiment ID).
model_name	str	''	Optional prefix for metric names to group them in TensorBoard. Defaults to empty string.

log_forecast_window_scalars(self, *, task_name, model_name, y_true, y_pred, forecast_start_timestamp, hyperparameters=None)

Log actual vs predicted as TensorBoard Scalars (no PNG / image summaries).

Tags mirror (model, task, forecast_origin, hyperparam_trial, variate), with model first so the Scalars sidebar groups under each model:

forecast/<model>/<task>/o<nanoseconds>/h<hash-or-default>/v<variate>/{actual|predicted}

The h… segment separates hyperparameter grid points that share the same forecast origin (otherwise scalar tags collide and TensorBoard draws one mangled series). Use hyperparameters={} for a single configuration (e.g. foundation models).

The o… segment is the first validation timestamp (forecast start), zero-padded so tag order matches time order.

Step is the forecast horizon index 0 … H-1 (within that window).

The Custom Scalars tab gets a layout aligned with TensorBoard's custom_scalar_demo.py: category = model, or model · hyperparams when the trial is not the default empty grid, one multiline chart per (task, forecast origin, variate) with two tag regexes (actual + predicted). Use Custom Scalars, not only Scalars, for that overlay.

Parameter	Type	Default	Description
task_name	str	-	Benchmark task (folder name).
model_name	str	-	Model name.
y_true	np.ndarray	-	Shape (H,) or (H, V).
y_pred	np.ndarray	-	Same shape as y_true.
forecast_start_timestamp	-	-	First timestep in the forecast (e.g. timestamps_pred[0]). Required and must parse to a valid time.
hyperparameters	Optional[Mapping[str, Any]]	None	Grid point used to produce y_true/y_pred (may be {} for a single-run model).

Raises: ValueError (If forecast_start_timestamp is missing or invalid.)

log_figure(self, figure, tag, step, *, dpi=100)

Log a Matplotlib figure to TensorBoard.

Parameter	Type	Default	Description
figure	-	-	Matplotlib figure object to log.
tag	str	-	Tag for the figure in TensorBoard.
step	int	-	Step number for this figure.
dpi	int	100	Resolution for the PNG written to TensorBoard.

log_image_file(self, image_path, tag, step)

Log an image from disk to TensorBoard.

Parameter	Type	Default	Description
image_path	str	-	Path to the image file to log.
tag	str	-	Tag for the image in TensorBoard.
step	int	-	Step number for this image.

log_training_progress(self, model_name, epoch, loss, val_loss=None, step=None)

Log training progress for real-time monitoring.

This method logs training and validation losses to TensorBoard for real-time monitoring of model training progress.

Parameter	Type	Default	Description
model_name	str	-	Name of the model being trained.
epoch	int	-	Current epoch number.
loss	float	-	Training loss value.
val_loss	Optional[float]	None	Validation loss value. If None, only training loss is logged.
step	Optional[int]	None	Global step for TensorBoard. If None, uses epoch as the step.

log_hparams(self, hparams, metrics, *, model_name='', task_name='', window_idx=0)

Log one trial for TensorBoard HParams (comparison table + parallel coords).

Follows TensorBoard guidance: declare the experiment with :func:hp.hparams_config on the root logdir once, then for each hyperparameter evaluation write a session (hp.hparams + validation metric scalars + session_end) under <tensorboard>/hparams_sessions/<trial_id>/ so each trial is its own run and metrics do not overwrite each other.

Always includes model, task, and window in the recorded hyperparameters so you can slice by model and task in the HParams UI.

Parameter	Type	Default	Description
hparams	dict	-	Model hyperparameter grid point (e.g. {"sp": 12}).
metrics	dict	-	Evaluation outputs containing numeric metrics (e.g. mae).
model_name	str	''	Benchmark model id (folder name).
task_name	str	''	Task folder name.
window_idx	int	0	Rolling validation window index for this row.

log_text(self, tag, text, step)

Log text to TensorBoard.

Parameter	Type	Default	Description
tag	str	-	Tag for the text in TensorBoard.
text	str	-	Text content to log.
step	int	-	Step number for this text.

log_scalar(self, tag, value, step)

Log a scalar value to TensorBoard.

Parameter	Type	Default	Description
tag	str	-	Tag for the scalar in TensorBoard.
value	float	-	Scalar value to log.
step	int	-	Step number for this scalar.

close(self)

Flush and close all logger resources.

This method flushes all log handlers and closes the TensorBoard writer. It can be called independently without using the context manager.

Parameters: (none) Returns: None (Flushes and closes all logging resources.)