Logging

Configure logging for backoff retry events.

Default Logger

Backoff uses the 'backoff' logger by default. It's configured with a NullHandler, so nothing is output unless you configure it.

Basic Setup

import logging

# Enable backoff logging
logging.getLogger('backoff').addHandler(logging.StreamHandler())
logging.getLogger('backoff').setLevel(logging.INFO)

Log Levels

• INFO - Logs all retry attempts
• ERROR - Logs only when giving up
• WARNING - Custom level for important retries
• DEBUG - Detailed information

# Only log when giving up
logging.getLogger('backoff').setLevel(logging.ERROR)

# Log all retries
logging.getLogger('backoff').setLevel(logging.INFO)

Custom Logger

Specify a custom logger by name or instance.

Logger by Name

@backoff.on_exception(
    backoff.expo,
    Exception,
    logger='my_custom_logger'
)
def my_function():
    pass

Logger Instance

import logging

my_logger = logging.getLogger('my_app.retries')
my_logger.addHandler(logging.FileHandler('retries.log'))
my_logger.setLevel(logging.WARNING)

@backoff.on_exception(
    backoff.expo,
    Exception,
    logger=my_logger
)
def my_function():
    pass

Disable Logging

Pass logger=None to disable all default logging:

@backoff.on_exception(
    backoff.expo,
    Exception,
    logger=None
)
def my_function():
    pass

Use with custom event handlers for complete control:

def my_custom_log(details):
    print(f"Custom log: {details}")

@backoff.on_exception(
    backoff.expo,
    Exception,
    logger=None,
    on_backoff=my_custom_log
)
def my_function():
    pass

Formatting

Basic Format

import logging

logging.basicConfig(
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    level=logging.INFO
)

logging.getLogger('backoff').addHandler(logging.StreamHandler())

Structured Logging (JSON)

import logging
import json

class JsonFormatter(logging.Formatter):
    def format(self, record):
        log_data = {
            'timestamp': self.formatTime(record),
            'level': record.levelname,
            'logger': record.name,
            'message': record.getMessage()
        }
        return json.dumps(log_data)

handler = logging.StreamHandler()
handler.setFormatter(JsonFormatter())

backoff_logger = logging.getLogger('backoff')
backoff_logger.addHandler(handler)
backoff_logger.setLevel(logging.INFO)

Multiple Handlers

Send logs to multiple destinations:

import logging

backoff_logger = logging.getLogger('backoff')

# Console handler
console_handler = logging.StreamHandler()
console_handler.setLevel(logging.WARNING)

# File handler
file_handler = logging.FileHandler('backoff.log')
file_handler.setLevel(logging.INFO)

# Add both handlers
backoff_logger.addHandler(console_handler)
backoff_logger.addHandler(file_handler)
backoff_logger.setLevel(logging.INFO)

Per-Function Logging

Use different loggers for different functions:

critical_logger = logging.getLogger('critical_ops')
routine_logger = logging.getLogger('routine_ops')

@backoff.on_exception(
    backoff.expo,
    Exception,
    logger=critical_logger,
    max_tries=10
)
def critical_operation():
    pass

@backoff.on_exception(
    backoff.expo,
    Exception,
    logger=routine_logger,
    max_tries=3
)
def routine_operation():
    pass

Complete Example

import logging
from logging.handlers import RotatingFileHandler

# Create custom logger
logger = logging.getLogger('myapp.backoff')
logger.setLevel(logging.INFO)

# Console handler with WARNING level
console_handler = logging.StreamHandler()
console_handler.setLevel(logging.WARNING)
console_format = logging.Formatter(
    '%(levelname)s: %(message)s'
)
console_handler.setFormatter(console_format)

# File handler with INFO level and rotation
file_handler = RotatingFileHandler(
    'backoff.log',
    maxBytes=10*1024*1024,  # 10MB
    backupCount=5
)
file_handler.setLevel(logging.INFO)
file_format = logging.Formatter(
    '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
file_handler.setFormatter(file_format)

# Add handlers
logger.addHandler(console_handler)
logger.addHandler(file_handler)

# Use in decorator
@backoff.on_exception(
    backoff.expo,
    Exception,
    logger=logger,
    max_tries=5
)
def my_function():
    pass