chameleon-log 2.0.0

Colourful handlers for Logbook, based on Rich and Journald.

🦎 ChameleonLog

Colourful logging handlers for Logbook.

ChameleonLog provides colorful, structured logging for Python applications using the Logbook.

• RichHandler: Beautiful console output with syntax highlighting and tracebacks using the Rich library (recommended for development).

• JournaldHandler: Structured logging to systemd journald with automatic level-based coloring and filtering (recommended for production/Live systems on Linux).

📦 Installation

Install ChameleonLog using pip:

pip install chameleon-log

Or using uv:

uv add chameleon-log

🔧 Optional Dependencies

To use the JournaldHandler for sending logs to systemd journald:

pip install chameleon-log[journald]

Or using uv:

uv add chameleon-log --extra journald

This will also install the journald-send package, requiring systemd-based Linux distros.

🚀 Usage

✨ RichHandler

For development and debugging in terminal environments, use RichHandler for colorful, formatted console output:

import logbook

from chameleon_log import RichHandler

# Create a RichHandler with default settings
handler = RichHandler()

with handler:
    logger = logbook.Logger(__name__)
    logger.info('Application started successfully')
    logger.warning('This is a warning message')
    logger.error('An error occurred')

The console parameter controls Rich formatting:

• True (default): Auto-detect based on isatty(). Use Rich rendering when the stream is a terminal.

• False: Disable Rich formatting, render plain output.

• A rich.Console instance: Use that Console directly. This is useful for sinking log output into an active Rich live display (e.g. a rich.progress.Progress bar).

Additionally, RichHandler accepts a rich_tracebacks boolean to control how exceptions are rendered:

• rich_tracebacks=True: Render exceptions using Rich Traceback objects when terminal rendering is enabled.

• rich_tracebacks=False (default): Append the plain-text formatted traceback to the log message. This is useful when logs are captured to files or external systems that do not support Rich rendering.

🖼️ Example output

🐧 JournaldHandler

For applications deployed on Linux servers or in production environments, use JournaldHandler to write logs directly to journald, using its native protocol. This provides more efficient troubleshooting capabilities compared to file-based logging or stdout / stderr capture.

Note

This is not the same as writing logs to stdout / stderr and letting journald collect them. The latter method makes you lose important metadata (timestamps, severity levels, extra fields) needed for effective log filtering and analysis.

Basic usage:

import logbook
from chameleon_log.journald import JournaldHandler

handler = JournaldHandler(syslog_identifier='my-app')

with handler:
    logger = logbook.Logger(__name__)
    logger.info('Application started successfully')
    logger.warning('This is a warning message')
    logger.error('An error occurred')

📝 Simple logging output:

🏗️ With extra fields for structured filtering:

Logbook provides two ways to attach extra fields:

Option 1: Use the extra= parameter (simple and direct)

import logbook
from chameleon_log.journald import JournaldHandler

handler = JournaldHandler(syslog_identifier='my-app')

with handler:
    logger = logbook.Logger(__name__)
    logger.info('User logged in', extra={'user_id': 123, 'action': 'login'})

Option 2: Use a Processor (for reusable context)

import logbook
from logbook import Logger, Processor
from chameleon_log.journald import JournaldHandler

handler = JournaldHandler()
    # or
handler = JournaldHandler(syslog_identifier='my-app')

# Use a Processor to inject context into multiple log records
def inject_request_context(record):
    record.extra['user_id'] = 123
    record.extra['request_id'] = 'abc-456'

with handler:
    logger = logbook.Logger(__name__)

    with Processor(inject_request_context):
        logger.info('User logged in')  # Fields injected automatically
        logger.info('Data processed')

View logs with journalctl:

journalctl -fu my-service
journalctl -t my-app F_USER_ID=123
journalctl -eu my-service -o json

Normally, you view your app logs with -u (unit), the syslog_identifier is helpful if your app scatters across many systemd units, you then can use journalctl -t to view all.

📖 Documentation

Full documentation is available at: https://chameleon-log.readthedocs.io

logbook-stubs

If you come here for logbook-stubs source, it is already moved to a separate repository.

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Logo by Freepik.