backtrader.utils.log_message module

Log Message Module - Logging utilities for backtrader.

This module is the single logging entry point for the whole framework. It builds on Python’s standard logging under the hood (no third-party spdlog dependency) but framework and user code should go through the helpers exposed here rather than importing logging directly:

• get_logger() — get a logger under the backtrader namespace.

• configure_logging() — opt-in handler/level setup (stderr + optional rotating file). Until this is called, backtrader emits nothing (a NullHandler is installed on the root backtrader logger).

• set_level() / reset_logging() — runtime level control / test reset.

• SpdLogManager — legacy per-file logger factory (daily rotation), kept for backward compatibility and reused internally by the strategy TradeLogger path.

See docs/LOGGING_GUIDELINES.md for level-usage conventions.

Example

>>> from backtrader.utils.log_message import get_logger, configure_logging
>>> configure_logging(level="INFO", log_file="run.log")
>>> logger = get_logger(__name__)
>>> logger.info("Strategy started")

# Legacy factory (still supported): >>> log_manager = SpdLogManager(file_name=”mylog.log”) >>> logger = log_manager.create_logger()

backtrader.utils.log_message.get_logger(name=None)

Return a logger under the backtrader namespace.

Parameters:

name – Usually __name__ of the calling module. If it already starts with "backtrader" it is used as-is; otherwise it is nested under the backtrader root (e.g. "mystuff" -> "backtrader.mystuff"). None returns the root logger.

Returns:

A logger in the backtrader hierarchy.

Return type:

logging.Logger

backtrader.utils.log_message.configure_logging(level='INFO', log_file=None, fmt=None, datefmt=None, console=True, max_bytes=10485760, backup_count=5, propagate=False)

Configure the backtrader logger hierarchy (opt-in).

Backtrader emits nothing until you call this. It configures only the backtrader logger (never the root logger), so it will not clobber a host application’s logging. Calling it again replaces backtrader-managed handlers (idempotent) while leaving host-added handlers untouched.

Parameters:

• level – Level as int (logging.INFO) or name ("INFO").

• log_file – If given, also write to this file via a RotatingFileHandler.

• fmt – Message format. Defaults to DEFAULT_FORMAT.

• datefmt – Date format. Defaults to DEFAULT_DATEFMT.

• console – Whether to add a stderr StreamHandler.

• max_bytes – Rotating file handler size before rollover.

• backup_count – Number of rotated backups to keep.

• propagate – Whether the backtrader logger propagates to the root logger (default False).

Returns:

The configured backtrader root logger.

Return type:

logging.Logger

backtrader.utils.log_message.set_level(level, name=None)

Set the level of a backtrader logger at runtime.

Parameters:

• level – Level as int or name.

• name – Sub-logger name (__name__-style). None targets the root.

backtrader.utils.log_message.reset_logging()

Remove backtrader-managed handlers and restore the default NullHandler.

Mainly useful in tests to return to the pristine, no-output state.

class backtrader.utils.log_message.SpdLogManager

Bases: object

Logger factory using the Python standard logging module.

Creates loggers with daily file rotation and optional console output. API is kept compatible with the previous spdlog-based implementation.

file_name

Name of the log file.

logger_name

Name for the logger.

rotation_hour

Hour of day for log rotation (0-23).

rotation_minute

Minute of hour for log rotation (0-59).

print_info

Whether to also print to console.

__init__(file_name='log_strategy_info.log', logger_name='hello', rotation_hour=0, rotation_minute=0, print_info=False)

Initialize the SpdLogManager.

Parameters:

• file_name – Name of the output log file.

• logger_name – Name for the logger.

• rotation_hour – Hour (0-23) to rotate log files daily.

• rotation_minute – Minute (0-59) to rotate log files.

• print_info – Whether to also output to console.

create_logger()

Create and return a configured logging.Logger instance.

Returns:

Logger with file handler (daily rotation) and optionally a console handler.

Return type:

logging.Logger