Quick Start

Basic Usage

Here’s a simple example to get you started with ctxlog:

import ctxlog

# Configure the logger (optional, uses sensible defaults)
ctxlog.configure(
    level="debug",  # or ctxlog.LogLevel.INFO
    timefmt="iso",  # ISO8601 format
    utc=True,  # Use UTC for timestamps
)

# Simple logging
logger.debug("This is a simple debug log")
logger.info("This is a simple info log")
logger.warning("This is a simple warning log")
logger.error("This is a simple error log")
logger.critical("This is a simple critical log")

# Structured logging with context
log = logger.ctx(user_id="user123", action="login").info("User logged in")

# Exception handling
try:
    # Some code that might raise an exception
    result = 1 / 0
except Exception as e:
    log = logger.ctx(dividing=1, by=0)
    log.exc(e).error("Division failed")

Log Chaining

For complex operations, you can create a hierarchy of logs:

def process_data(data):
    log = logger.new("data_processing")

    try:
        validate_data(log.new("data_validation"), data)
    except Exception as e:
        log.exc(e).error("Data validation failed")

    log.info("Data processed successfully")

def validate_data(log, data):
    log = log.ctx(key=data["key"])

    # Validation happens

    log.info("Data validation successful")

process_data({"key": "value"})

Output Handlers

ctxlog supports multiple output handlers:

import ctxlog
from ctxlog import LogLevel, ConsoleHandler, FileHandler, FileRotation

# Configure with default console handler
ctxlog.configure(
    level=LogLevel.INFO,
    timefmt="iso",  # or "%Y-%m-%d %H:%M:%S"
    utc=True,
)

# Configure with custom handlers
ctxlog.configure(
    level=LogLevel.INFO,
    handlers=[
        ConsoleHandler(
            level=LogLevel.INFO,
            serialize=False,  # Human-readable format
            color=True,
            use_stderr=False,
        ),
        FileHandler(
            level=LogLevel.DEBUG,  # More verbose in file
            serialize=True,  # JSON format
            file_path="./app.log",
            rotation=FileRotation(
                size="20MB",  # Rotate when file reaches 20MB
                keep=5,  # Keep 5 rotated files
                compression="gzip",  # Compress old files
            ),
        ),
    ],
)