chameleon-log 1.1.1

Colourful handlers for Logbook, based on Rich and Journald.

Colourful logging handlers for Logbook.

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

• 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 (Linux only):

pip install chameleon_log[journald]

Or using uv:

uv add chameleon_log --extra journald

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

Usage

RichHandler (Development)

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')

This will produce beautiful console output with syntax highlighting and formatted tracebacks.

Example Output

JournaldHandler Usage (Production/Live Systems)

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

Note

Writing directly to journald is not the same as writing logs to stdout/stderr and letting journald collect them. The latter loses 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

License

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

Logo by Freepik.