Decima

Python Version License

Decima is a robust, custom logging library for Python that enhances your application's observability with colorful console output and structured JSON logging. Designed for clarity and ease of use, it helps developers track down issues faster with a dedicated TRACE level and automatic file management.

Key Features

  • 🎨 Colorful Console Output: Instantly distinguish log levels with vibrant color coding (Cyan for TRACE, Blue for DEBUG, Red for ERROR, etc.).
  • 📊 Structured JSON Logging: Automatically writes logs to .jsonl files, perfect for ingestion by log analysis tools.
  • 🔍 Custom TRACE Level: Includes a TRACE (level 5) severity for ultra-granular debugging, below the standard DEBUG.
  • 📁 Automated File Management: seamlessly handles log file creation, including timestamped run logs and cumulative JSON logs.
  • ⚡ Simple Configuration: Get up and running with a single static setup call.

Installation

Decima is a Python library. Since it is not yet on PyPI, you can install it directly from the git repository using pip or uv:

# Using pip
pip install "git+https://github.com/cvasilatos/decima.git"

# Using uv
uv add "git+https://github.com/cvasilatos/decima.git"

(Note: Adjust installation command based on your package registry status. If running locally, ensure you build and install the wheel.)

Usage

Integrating Decima into your project is straightforward.

1. Setup Logging

Initialize the logger at the start of your application entry point:

import logging
from decima import CustomLogger

# Configure logging:
# - folder: Directory to store log files
# - filename: Base name for log files
# - level: Minimum logging level (e.g., "DEBUG", "INFO")
# - class_length: Max length for logger name in console output (for alignment)
CustomLogger.setup_logging(
    folder="logs",
    filename="app",
    level="DEBUG",
    class_length=20
)

# Get a logger instance
logger = logging.getLogger("MyApp")

2. Logging Messages

You can now use the standard logging methods, plus the new trace method (if using CustomLogger explicitly or if the level is registered):

logger.info("Application started successfully.")
logger.warning("Configuration file missing, using defaults.")
logger.error("Failed to connect to database.")

# For Trace level (level 5)
# Note: Ensure usage complies with the CustomLogger class capabilities
custom_logger = logging.getLogger("MyApp")
if isinstance(custom_logger, CustomLogger):
    custom_logger.trace("Entering complex calculation loop...")

To fully utilize the trace method with type safety, you might want to ensure your logger is typed as CustomLogger.

Output Formats

Console Output:

2023-10-27 10:00:00,123 - [INFO] - MyApp - Application started successfully.

(With appropriate colors applied)

JSON Output (logs/app.jsonl):

{"timestamp": "2023-10-27T10:00:00.123456-05:00", "level": "INFO", "name": "MyApp", "message": "Application started successfully."}

specific Configuration

  • LogFormatter: Handles the colorization and formatting of console logs.
  • JsonFormatter: Handles the serialization of log records into JSON structure.
  • class_length: Truncates the logger name in the console output to keep columns aligned, preserving the end of the name.

Development

This project uses uv for dependency management and hatch for building.

Setting up the environment

uv sync --all-extras --dev

Running Tests

uv run pytest

Linting & Formatting

uv run ruff check .
uv run ruff format .

Building Documentation

Decima uses mkdocs for documentation.

uv run mkdocs serve

License

This project is licensed under the MIT License. See the LICENSE file for details.