Configuration

Global Configuration

ctxlog uses a global configuration that can be customized using the configure function:

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
            ),
        ),
    ],
)

Configuration Parameters

level

The global log level threshold. Logs below this level will not be emitted.

# Using enum
level=ctxlog.LogLevel.INFO

# Using string
level="info"

# Using integer
level=20

Available log levels:

• DEBUG (10)

• INFO (20)

• WARNING (30)

• ERROR (40)

• CRITICAL (50)

timefmt

The timestamp format for log entries:

# ISO8601 format (default)
timefmt="iso"

# Custom strftime format
timefmt="%Y-%m-%d %H:%M:%S"

utc

Whether to use UTC for timestamps:

# Use UTC (default: False)
utc=True

# Use local time
utc=False

handlers

A list of output handlers. If not provided, a default ConsoleHandler is used:

from ctxlog import ConsoleHandler, FileHandler

handlers=[
    ConsoleHandler(),
    FileHandler(file_path="./app.log"),
]

Console Handler

The ConsoleHandler outputs logs to the console (stdout/stderr):

from ctxlog import ConsoleHandler, LogLevel

ConsoleHandler(
    level=LogLevel.INFO,  # Handler-specific level (optional)
    serialize=False,      # Whether to output as JSON
    color=True,           # Whether to use colored output
    use_stderr=False,     # Whether to use stderr for all logs
)

File Handler

The FileHandler outputs logs to a file:

from ctxlog import FileHandler, FileRotation, LogLevel

FileHandler(
    level=LogLevel.DEBUG,  # Handler-specific level (optional)
    serialize=True,        # Whether to output as JSON
    file_path="./app.log", # Path to the log file
    rotation=None,         # File rotation configuration (optional)
)

File Rotation

The FileRotation class configures log file rotation:

from ctxlog import FileRotation

# Size-based rotation
rotation=FileRotation(
    size="20MB",        # Rotate when file reaches this size
    keep=5,             # Keep this many rotated files
    compression="gzip", # Compress old files (gzip or zip)
)

# Time-based rotation
rotation=FileRotation(
    time="00.00",       # Rotate at this time (HH.MM)
    keep=5,             # Keep this many rotated files
    compression="gzip", # Compress old files (gzip or zip)
)

Multiple Handlers

You can configure multiple handlers with different levels and formats:

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

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
            ),
        ),
    ],
)