Efficient Logging in Python with Loguru

Installation

pip install loguru

Getting Started

The core concept in Loguru is straightforward: the logger.

from loguru import logger

logger.info("This is log info!")
logger.warning("This is log warn!")
logger.error("This is log error!")
logger.debug("This is log debug!")

Loguru comes pre-configured with basic settings, automatically outputting timestamp, log level, module name, line number, and more. Different log levels are displayed in different colors for easy identification, making it truly out-of-the-box ready!

Customization

To customize log levels, formats, or save logs to files, Loguru simplifies the process compared to Python's built-in logging module. Instead of Handlers and Formatters, you only need the add() function:

from loguru import logger

logger.add('application.log')
logger.debug('this is a debug message')

You don't need to declare a FileHandler as you would with the logging module. A single add() statement handles everything. After running this code, you'll find the debug message in application.log.

Removing Configurations

The counterpart to add() is remove(), which allows you to delete added configurations:

from loguru import logger

log_handler = logger.add('application.log')
logger.debug('This is the first log message!')
logger.remove(log_handler)
logger.debug('This message won\'t be logged to the file!')

Comprehensive Parameters

Loguru offers extensive support for file output configuration, including multiple file outputs, level-specific outputs, automatic file creation based on size, and automatic deletion of old files. Let's examine the detailed parameters of the add() function:

Basic Syntax

add(sink, *, level='DEBUG', format='<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>', filter=None, colorize=None, serialize=False, backtrace=True, diagnose=True, enqueue=False, catch=True, **kwargs)

Core Parameters

• sink: Can be a file object (e.g., sys.stderr or open('file.log', 'w')), a string or pathlib.Path object (file path), a custom method, a logging module Handler (like FileHandler or StreamHandler), or a coroutine function.
• level: Log output and storage level.
• format: Log format template.
• filter: Optional directive to determine if each record should be sent to the sink.
• colorize: Whether color markers in formatted messages should be converted to ANSI codes for terminal coloring or stripped.
• serialize: Whether records should be converted to JSON strings before being sent to the sink.
• backtrace: Whether the formatted exception traceback should be extended beyond the capture point to show the full stack trace.
• diagnose: Whether variable values should be displayed in exception traces to simplify debugging. Recommended to set to False in production to avoid sensitive data leakage.
• enqueue: Whether logged messages should pass through a multiprocess-safe queue before reaching the sink. Useful when logging to files from multiple processes, making log calls non-blocking.
• catch: Whether errors occurring when the sink processes log messages should be automatically caught. If True, exception messages are displayed on sys.stderr but don't propagate to the sink, preventing application crashes.

File-Specific Parameters

When the sink is a file path, these additional parameters apply:

• rotation: Condition for when the current file should be closed and a new one started.
• retention: Instruction for filtering old files, which will be deleted during rotation or program termination.
• compression: Compression or archive format for log files when closed.
• delay: Whether to create the file immediately after configuring the sink or when the first message is logged. Defaults to False.
• mode: File opening mode, defaults to 'a' (append mode).
• buffering: Buffering strategy, defaults to 1 (line buffered).
• encoding: File encoding, defaults to locale.getpreferredencoding() if None.

Log File Rotation

The rotation parameter in add() allows creating new log files based on specific conditions:

# Create a new log file daily at midnight
logger.add('runtime_{time}.log', rotation='00:00')

# Create a new log file when it exceeds 500 MB
logger.add('runtime_{time}.log', rotation="500 MB")

# Create a new log file every week
logger.add('runtime_{time}.log', rotation='1 week')

Log Retention

The retention parameter sets how long log files should be kept:

# Keep log files for a maximum of 15 days
logger.add('runtime_{time}.log', retention='15 days')

# Keep a maximum of 10 log files
logger.add('runtime_{time}.log', retention=10)

# Keep log files for a maximum of 5 hours
import datetime
from loguru import logger

logger.add('runtime_{time}.log', retention=datetime.timedelta(hours=5))

Log Compression

The compression parameter configures compression format for log files to save storage space:

# Save logs as zip files
logger.add('runtime_{time}.log', compression='zip')

Supported formats include: gz, bz2, xz, lzma, tar, tar.gz, tar.bz2, tar.xz

String Formatting

Loguru provides convenient string formatting similar to str.format():

logger.info('Python version {} supports {} as a great feature!', 3.7, feature='f-strings')

Exception Handling

Loguru offers a decorator for automatic exception capture with detailed logging:

from loguru import logger

@logger.catch
def calculate_value(x, y, z):
    # Errors are caught and logged automatically
    return 1 / (x + y + z)

calculate_value(0, 0, 0)

This will produce a detailed traceback in the logs, making debugging much easier.

Additional Resources

For more information about Loguru, visit the official documentation:

Loguru Documentation