speechbrain.utils.logger module

Managing the logger, utilities

Author

Fang-Pen Lin 2012 https://fangpenlin.com/posts/2012/08/26/good-logging-practice-in-python/
Peter Plantinga 2020
Aku Rouhe 2020

Summary

Classes:

`MultiProcessLoggerAdapter`	Logger adapter that handles multi-process logging, ensuring logs are written only on the main process if specified.
`TqdmCompatibleStreamHandler`	TQDM compatible StreamHandler.

Functions:

`format_order_of_magnitude`	Formats number to the appropriate order of magnitude for printing.
`get_environment_description`	Returns a string describing the current Python / SpeechBrain environment.
`get_logger`	Retrieves a logger with the specified name, applying a log level from the environment variable `SB_LOG_LEVEL` if set, or defaults to `INFO` level.
`setup_logging`	Setup logging configuration.

Reference

class speechbrain.utils.logger.MultiProcessLoggerAdapter(logger, extra=None)[source]

Bases: LoggerAdapter

Logger adapter that handles multi-process logging, ensuring logs are written only on the main process if specified. This class extends logging.LoggerAdapter and provides additional functionality for controlling logging in multi-process environments, with the option to limit logs to the main process only.

This class is heavily inspired by HuggingFace Accelerate toolkit: https://github.com/huggingface/accelerate/blob/85b1a03552cf8d58e036634e004220c189bfb247/src/accelerate/logging.py#L22

log(level: int, msg: str, *args, **kwargs)[source]

Logs a message with the specified log level, respecting the main_process_only flag to decide whether to log based on the current process.

Parameters:

level (int) – Logging level (e.g., logging.INFO, logging.WARNING).
msg (str) – The message to log.
*args (tuple) – Additional positional arguments passed to the logger.
**kwargs (dict) – Additional keyword arguments passed to the logger, including: - main_process_only (bool): If True, log only from the main process (default: True). - stacklevel (int): The stack level to use when logging (default: 2).

Notes

If main_process_only is True, the log will only be written if the current process is the main process, as determined by if_main_process().

warning_once(*args, **kwargs)[source]

Logs a warning message only once by using caching to prevent duplicate warnings.

Parameters:

*args (tuple) – Positional arguments passed to the warning log.
**kwargs (dict) – Keyword arguments passed to the warning log.

Notes

This method is decorated with functools.lru_cache(None), ensuring that the warning message is logged only once regardless of how many times the method is called.

speechbrain.utils.logger.get_logger(name: str) → MultiProcessLoggerAdapter[source]

Retrieves a logger with the specified name, applying a log level from the environment variable SB_LOG_LEVEL if set, or defaults to INFO level.

If the environment variable SB_LOG_LEVEL is not defined, it defaults to INFO level and sets this level in the environment for future use. The environment variable can be set manually or automatically in Brain class following setup_logging.

Parameters:: name (str) – The name of the logger to retrieve.
Returns:: An instance of MultiProcessLoggerAdapter wrapping the logger with the specified name.
Return type:: MultiProcessLoggerAdapter

speechbrain.utils.logger.setup_logging(config_path='log-config.yaml', overrides={}, default_level='DEBUG')[source]

Setup logging configuration.

Parameters:

config_path (str) – The path to a logging config file.
overrides (dict) – A dictionary of the same structure as the config dict with any updated values that need to be applied.
default_level (str) – The log level to use if the config file is not found. Python logging allows ints or strings: https://docs.python.org/3/library/logging.html#logging.Logger.setLevel but strings are used here as environment variables have to be strings. The available levels are listed here: https://docs.python.org/3/library/logging.html#levels

class speechbrain.utils.logger.TqdmCompatibleStreamHandler(stream=None)[source]

Bases: StreamHandler

TQDM compatible StreamHandler.

Writes and prints should be passed through tqdm.tqdm.write so that the tqdm progressbar doesn’t get messed up.

emit(record)[source]: TQDM compatible StreamHandler.

speechbrain.utils.logger.format_order_of_magnitude(number, abbreviate=True)[source]

Formats number to the appropriate order of magnitude for printing.

Parameters:

number (int, float) – The number to format.
abbreviate (bool) – Whether to use abbreviations (k,M,G) or words (Thousand, Million, Billion). Numbers will be either like: “123.5k” or “123.5 Thousand”.

Returns:

The formatted number. Note that the order of magnitude token is part of the string.

Return type:

str

Example

>>> print(format_order_of_magnitude(123456))
123.5k
>>> print(format_order_of_magnitude(0.00000123, abbreviate=False))
1.2 millionths
>>> print(format_order_of_magnitude(5, abbreviate=False))
5

speechbrain.utils.logger.get_environment_description()[source]

Returns a string describing the current Python / SpeechBrain environment.

Useful for making experiments as replicable as possible.

Returns:: The string is formatted ready to be written to a file.
Return type:: str

Example

>>> get_environment_description().splitlines()[0]
'SpeechBrain system description'