loggers

loggers#

Metric and artifact loggers

Classes#

ClearMLLogger

A lightweight adapter that logs training runs to ClearML.

FileLogger

Logger

Based class for implementing loggers for RL algorithms.

MLFlowLogger

MLFlow Logger

class prt_rl.common.loggers.ClearMLLogger(project_name: str, task_name: str, logging_freq: int = 1)[source]#

A lightweight adapter that logs training runs to ClearML.

This logger mirrors the behavior of an MLflow-style logger while taking advantage of ClearML primitives:

Creates and manages a ClearML Task under the specified project.
Logs parameters as static configuration (via ClearML configuration / hyperparameters panels).
Logs scalars (metrics) with optional “group/metric” naming that maps to ClearML’s (title, series) convention.
Saves an agent object as a versioned artifact attached to the Task.
Registers a policy as a first-class ClearML Model in the Model Registry (including design/metadata and uploaded weights), so it is discoverable and diffable alongside other models.

The class expects ClearML to be installed and configured (e.g., via clearml-init or environment variables). It does not start or manage any background queues; uploads occur synchronously within each call.

Variables:

project_name (str) – Name of the ClearML project under which the Task will be created.
task_name (str) – Name of the ClearML Task (run) created for this logger instance.
logging_freq (int) – Frequency hint inherited from Logger. If your training loop calls log_scalar every step, you may use this value to conditionally log every n-th step (your loop is responsible for honoring it).
iteration (int) – Monotonically increasing counter used as the default iteration (step) for scalar logging when none is supplied explicitly.
task (clearml.Task) – The underlying ClearML Task object created during initialization.
_logger (clearml.Logger) – The ClearML experiment logger obtained from task.get_logger().

Notes

Scalar naming: If you pass “loss/train” to log_scalar, it will be stored with title=”loss” and series=”train”. If no slash is present, the title defaults to “metrics” and the entire name becomes the series.
Parameters: Parameters are intended to be static (do not change over training). They are recorded into ClearML’s configuration/hyperparameters view to support comparison and reproducibility.
Models vs. Artifacts: save_policy registers a ClearML Model (appears in the Model Registry) and uploads weights (e.g., a PyTorch state_dict or a pickle fallback). save_agent uploads a file or object as a Task artifact (appears under the run’s Artifacts panel).
Environment: Ensure ClearML is configured to point at your server (self-hosted or SaaS) via clearml-init or environment variables (CLEARML_API_HOST, CLEARML_API_ACCESS_KEY, CLEARML_API_SECRET_KEY).

Examples

Basic usage in a training loop:

>>> logger = ClearMLLogger(project_name="Demo/PRT", task_name="PPO CartPole")
>>> logger.log_parameters({"algo": "PPO", "seed": 42, "lr": 3e-4})
>>> for step in range(1000):
...     loss = 1.0 / (step + 1)
...     reward = step * 0.1
...     logger.log_scalar("loss/train", loss)         # auto step (0,1,2,...)
...     logger.log_scalar("reward/mean", reward)
>>> # Save objects
>>> agent = {"type": "ppo", "notes": "demo"}
>>> logger.save_agent(agent)                          # artifact on the Task
>>> policy = my_policy                                # your BasePolicy impl
>>> logger.save_policy(policy)                        # Model in Registry
>>> logger.close()

See also

clearml.Task: Underlying experiment/run object.
clearml.OutputModel: Used for registering models in the ClearML registry.

Raises:: ImportError – If the clearml package is not installed or cannot be imported.

close()[source]#: Closes and cleans up the ClearML logger.

Logs an artifact file.

Parameters:

path (str) – Path to the artifact file.
name (str) – Name of the artifact.

log_metrics(metrics: dict[str, float], iteration: int | None = None) → None#

Logs multiple scalar metrics.

Parameters:

metrics (dict) – Dictionary of metric names and their corresponding values.
iteration (int, optional) – Iteration number.

log_parameters(params: dict) → None[source]#

Logs a dictionary of parameters. Parameters are values used to initialize but do not change throughout training.

Parameters:: params (dict) – Dictionary of parameters.

log_scalar(name: str, value: float, iteration: int | None = None) → None[source]#

Logs a scalar value. Scalar values are any metric or value that changes throughout training.

Parameters:

name (str) – Name of the scalar value.
value (float) – Value of the scalar value.
iteration (int, optional) – Iteration number.

should_log(iteration: int) → bool#

Determines whether to log based on the current iteration and logging frequency.

Parameters:: iteration (int) – Current iteration number.
Returns:: True if logging should occur, False otherwise.
Return type:: bool

class prt_rl.common.loggers.FileLogger(output_dir: str, logging_freq: int = 1)[source]#

close()[source]#: Writes the saved parameters and scalar metrics to a file.

Logs an artifact file.

Parameters:

path (str) – Path to the artifact file.
name (str) – Name of the artifact.

log_file(path: str, name: str, move: bool = False) → None[source]#: Saves the given file to the output_dir/name folder. Creates the folder if it does not exist.

log_metrics(metrics: dict[str, float], iteration: int | None = None) → None#

Logs multiple scalar metrics.

Parameters:

metrics (dict) – Dictionary of metric names and their corresponding values.
iteration (int, optional) – Iteration number.

log_parameters(params: dict) → None[source]#: Logs a dictionary of parameters.

log_scalar(name: str, value: float, iteration: int | None = None) → None[source]#: Logs scalar values, storing them sequentially or with a provided iteration number.

should_log(iteration: int) → bool#

Determines whether to log based on the current iteration and logging frequency.

Parameters:: iteration (int) – Current iteration number.
Returns:: True if logging should occur, False otherwise.
Return type:: bool

class prt_rl.common.loggers.Logger(logging_freq: int = 1)[source]#

Based class for implementing loggers for RL algorithms.

close()[source]#: Performs any necessary logger cleanup.

Logs an artifact file.

Parameters:

path (str) – Path to the artifact file.
name (str) – Name of the artifact.

log_metrics(metrics: dict[str, float], iteration: int | None = None) → None[source]#

Logs multiple scalar metrics.

Parameters:

metrics (dict) – Dictionary of metric names and their corresponding values.
iteration (int, optional) – Iteration number.

log_parameters(params: dict) → None[source]#

Logs a dictionary of parameters. Parameters are values used to initialize but do not change throughout training.

Parameters:: params (dict) – Dictionary of parameters.

log_scalar(name: str, value: float, iteration: int | None = None) → None[source]#

Logs a scalar value. Scalar values are any metric or value that changes throughout training.

Parameters:

name (str) – Name of the scalar value.
value (float) – Value of the scalar value.
iteration (int, optional) – Iteration number.

should_log(iteration: int) → bool[source]#

Determines whether to log based on the current iteration and logging frequency.

Parameters:: iteration (int) – Current iteration number.
Returns:: True if logging should occur, False otherwise.
Return type:: bool

class prt_rl.common.loggers.MLFlowLogger(experiment_name: str, *, tracking_uri: str | None = None, run_name: str | None = None, log_system_metrics: bool = False, logging_freq: int = 1)[source]#

MLFlow Logger

Notes

psutil must be installed with pip to log system cpu metrics. pynvml must be installed with pip to log gpu metrics.

References

[1] https://mlflow.org/docs/latest/python_api/mlflow.html

close()[source]#: Closes and cleans up the MLFlow logger.

Logs an artifact file.

Parameters:

path (str) – Path to the artifact file.
name (str) – Name of the artifact.

log_directory(dir: str, path: str | None = None) → None[source]#: Logs a file as an artifact to MLFlow. :param path: Path to the file to log. :type path: str :param name: Name of the artifact in MLFlow. :type name: str

log_figure(fig, name: str, iteration: int | None = None) → None[source]#: Logs a matplotlib figure to MLFlow as an artifact. :param fig: The figure to log. :type fig: matplotlib.figure.Figure :param name: Name of the figure artifact. :type name: str :param iteration: Iteration number for logging. :type iteration: int, optional

log_metrics(metrics: dict[str, float], iteration: int | None = None) → None#

Logs multiple scalar metrics.

Parameters:

metrics (dict) – Dictionary of metric names and their corresponding values.
iteration (int, optional) – Iteration number.

log_parameters(params: dict) → None[source]#: Logs a dictionary of parameters. Parameters are values used to initialize but do not change throughout training. :param params: Dictionary of parameters. :type params: dict

log_scalar(name: str, value: float, iteration: int | None = None) → None[source]#: Logs a scalar value to MLFlow. :param name: Name of the scalar value. :type name: str :param value: Value of the scalar value. :type value: float :param iteration: Iteration number. :type iteration: int, optional

log_tags(tags: dict) → None[source]#: Logs a dictionary of tags to MLFlow. :param tags: Dictionary of tags to log. :type tags: dict

should_log(iteration: int) → bool#

Determines whether to log based on the current iteration and logging frequency.

Parameters:: iteration (int) – Current iteration number.
Returns:: True if logging should occur, False otherwise.
Return type:: bool

`ClearMLLogger`	A lightweight adapter that logs training runs to ClearML.
`FileLogger`
`Logger`	Based class for implementing loggers for RL algorithms.
`MLFlowLogger`	MLFlow Logger

loggers

Contents

loggers#

Classes#