🦎 ChameleonLog

ChameleonLog Logo

Colourful logging handlers for Logbook.

Made in Vietnam PyPI PyPI - Python Version PyPI - License Common Changelog Documentation Status

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

Rich Handler Output Rich Handler 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.

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:

Journald Simple Output

🏗️ With extra fields for structured filtering:

Logbook provides two ways to attach extra fields:

Journald Extra Fields Output

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.

Project links

Data verified by PyPI on Aug 13, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (3.2.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for quan from gravatar.com quan

Credits

PyPI data
Data sourced directly from PyPI's database.

Author: Nguyễn Hồng Quân

GitHub Statistics

Data verified by PyPI on Aug 13, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.12

Provides Extra

journald sentry

Tags

journald logbook logging rich sentry

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

chameleon_log-3.0.0.tar.gz (115.3 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

chameleon_log-3.0.0-py3-none-any.whl (19.1 kB view details)

Uploaded Python 3

File details

Details for the file chameleon_log-3.0.0.tar.gz.

File metadata

  • Download URL: chameleon_log-3.0.0.tar.gz
  • Upload date:
  • Size: 115.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for chameleon_log-3.0.0.tar.gz
Algorithm Hash digest
SHA256 6e5ab6887af78a0f5dfa48f6867d55200c5ca6f8c96b6af5fcd9eee1b66880ea
MD5 7805835e2529646fa9bed7d421c2f258
BLAKE2b-256 9084777c59dea8025bcea1b6f0917046f99055e5d181f4a5bbc652f65bbac7f1

See more details on using hashes here.

Provenance

The following attestation bundles were made for chameleon_log-3.0.0.tar.gz:

Publisher: ci.yml on hongquan/chameleon-log

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chameleon_log-3.0.0-py3-none-any.whl.

File metadata

  • Download URL: chameleon_log-3.0.0-py3-none-any.whl
  • Upload date:
  • Size: 19.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for chameleon_log-3.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 4e9ab3c5261861e3a6fb301008d4b3e3bfaf091afcf5ebc951014ec8d88f31d3
MD5 1617a25f64e1a79ef71ee8f7837ae787
BLAKE2b-256 c6812ffc43108ef794f2ae40d5478b817b0ff0825ed09ada7afb39e1c8acc58a

See more details on using hashes here.

Provenance

The following attestation bundles were made for chameleon_log-3.0.0-py3-none-any.whl:

Publisher: ci.yml on hongquan/chameleon-log

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

3.2.0

2 files

3.1.0

2 files

This release

3.0.0 This release

2 files

2.0.0

2 files

1.9.0

2 files

1.8.0

2 files

1.7.2

2 files

1.6.0

2 files

1.5.0

2 files

1.4.0

2 files

1.3.0

2 files

1.2.0

2 files

1.1.3

2 files

1.1.2

2 files

1.1.1

2 files

1.1.0

2 files

1.0.0

2 files

0.2.0

2 files

0.1.1

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page