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, *, log_dir=None, script_name=None, backend='auto', retention_days=30, _debug_scopes=())

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 single file via a RotatingFileHandler. Mutually exclusive with log_dir.

• log_dir – If given, enable the iteration-29 split-file layout log_dir/<script>/<YYYY_MM_DD>/{error,warning,info}.log (plus debug.log when level=DEBUG). <script> comes from script_name or auto-detection of sys.argv[0].

• script_name – Directory name under log_dir. None auto-detects from sys.argv[0] (xxx/run.py -> xxx_run).

• backend – "auto" (default; prefer the optional spdlog package, fall back to stdlib with one diagnostic), "spdlog" (raise ImportError if unavailable) or "stdlib".

• retention_days – Date directories older than this many days under the script’s own directory are removed at configure/rollover time.

• 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 (log_file).

• backup_count – Number of rotated backups to keep (log_file).

• 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. A root-level update with active split-file logging atomically rebuilds its handler matrix, so a DEBUG transition creates debug.log and is inherited by optimization workers. A named DEBUG update creates a DEBUG sink restricted to that logger’s hierarchy, leaving unrelated loggers at the configured root level.

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. Also flushes and releases any spdlog-side resources held by managed handlers.

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

class backtrader.utils.log_message.SpdlogHandler

Bases: _NonFatalHandlerMixin, Handler

spdlog-backend handler mirroring _DailyLevelFileHandler.

The framework layer owns the layout: the Python formatter renders the full line and spdlog writes it with pattern %v (message only), so line format matches the stdlib backend. Date rollover drops and reopens the underlying spdlog logger on the new path.

__init__(spdlog_mod, script_dir, level_name, handler_level, exact_filter, retention_days)

emit(record)

Do whatever it takes to actually log the specified logging record.

This version is intended to be implemented by subclasses and so raises a NotImplementedError.

flush()

Ensure all logging output has been flushed.

This version does nothing and is intended to be implemented by subclasses.

close()

Tidy up any resources used by the handler.

This version removes the handler from an internal map of handlers, _handlers, which is used for handler lookup by name. Subclasses should ensure that this gets called from overridden close() methods.

backtrader.utils.log_message.flush_all()

Flush every managed handler (use before reading log files in tests).

backtrader.utils.log_message.set_throttle(enabled)

Enable/disable storm suppression (diagnostic mode: disable).

backtrader.utils.log_message.throttled_error(logger, key, msg, *args, every=100, window=60.0, exc_info=True)

logger.error with storm suppression: first full, repeats summarized.

backtrader.utils.log_message.throttled_warning(logger, key, msg, *args, every=100, window=60.0, exc_info=True)

logger.warning with storm suppression (same contract as error).

backtrader.utils.log_message.flush_throttle_summary()

Emit one summary line per key with unreported repeats (atexit hook).