chameleon-log 3.2.0

🔧 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.

🐧 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.

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.