Skip to content

Arlogi Library Documentation

Version: 0.601.04

Python: 3.13+

License: MIT

Comprehensive documentation for the arlogi logging library - a robust, type-safe, and highly configurable logging solution for Python applications.

Key Features

  • ๐ŸŽฏ Caller Attribution: Trace log calls across function boundaries using caller_depth parameter
  • ๐Ÿ“Š Custom TRACE Level: Ultra-detailed logging below DEBUG (level 5)
  • ๐ŸŽจ Rich Console Output: Beautiful colored terminal output with Rich library
  • ๐Ÿ“ JSON Logging: Structured JSON logs for machine parsing and analysis
  • ๐Ÿ”ง Type-Safe Configuration: Modern LoggingConfig dataclass for compile-time safety
  • ๐Ÿงช Test-Aware: Automatic test mode detection for seamless pytest integration
  • ๐Ÿ”Œ Multiple Handlers: Console, JSON file, and Syslog support
  • ๐Ÿ—๏ธ Modular Handlers: Dedicated JSON-only and syslog-only loggers

Quick Start

from arlogi import LoggingConfig, LoggerFactory, get_logger

# Configure logging using modern architecture
config = LoggingConfig(level="INFO")
LoggerFactory._apply_configuration(config)

# Get logger and log
logger = get_logger(__name__)
logger.info("Hello, Arlogi!", caller_depth=0)

Output:

INFO    Hello, Arlogi!        [module()]

Documentation Guide

Getting Started

  • Installation and basic usage: Get started with arlogi quickly
  • Caller Attribution Feature: Learn about the unique caller_depth parameter

Documentation

๐Ÿ“– User Documentation

  1. User Guide

  2. Installation and setup

  3. Basic usage patterns
  4. Configuration options
  5. Caller attribution guide
  6. Common patterns

  7. Troubleshooting tips

  8. Configuration Guide

  9. Modern LoggingConfig architecture

  10. Global configuration patterns
  11. Per-module level overrides
  12. Handler configuration
  13. Environment-specific setups

  14. Dynamic configuration

  15. Caller Attribution Examples

  16. Basic depth usage (caller_depth=0, caller_depth=1)

  17. Cross-module attribution
  18. Real-world patterns (web APIs, databases, background jobs)
  19. Performance considerations
  20. Testing examples

๐Ÿ”ง Developer Documentation

  1. Developer Guide

  2. Development setup

  3. Project structure
  4. Testing strategies
  5. Code quality standards
  6. Release process

  7. Contributing guidelines

  8. Architecture Documentation

  9. System design overview

  10. Architecture diagrams (C4 model)
  11. Design patterns
  12. Component reference
  13. Data flow
  14. Extensibility points

๐Ÿ“š API Reference

  1. API Reference

  2. Public API functions

  3. LoggingConfig reference
  4. LoggerProtocol interface
  5. Handler classes
  6. Log levels
  7. Type hints
  8. Examples

Key Features by Category

๐ŸŽฏ Caller Attribution

Feature Description Documentation
caller_depth=0 Shows current function Examples
caller_depth=1 Shows immediate caller Examples
caller_depth=2+ Shows deeper context Examples
Cross-module Tracks across modules Examples

๐Ÿ”ง Configuration

Feature Description Documentation
LoggingConfig Type-safe configuration Config Guide
Module Levels Per-module overrides Config Guide
JSON Logging Structured output Config Guide
Syslog System log integration Config Guide

๐Ÿ“Š Log Levels

Level Value Use Case
TRACE 5 Function entry/exit, variable dumps
DEBUG 10 Detailed troubleshooting
INFO 20 General application flow
WARNING 30 Unexpected but recoverable
ERROR 40 Errors that don't stop execution
CRITICAL 50 Serious failures

๐ŸŽจ Handlers

Handler Purpose Documentation
ColoredConsoleHandler Rich console output API Reference
JSONHandler JSON to stderr API Reference
JSONFileHandler JSON to file API Reference
ArlogiSyslogHandler Syslog output API Reference

Quick Reference

Basic Setup

from arlogi import LoggingConfig, LoggerFactory, get_logger

# Configure
config = LoggingConfig(level="INFO")
LoggerFactory._apply_configuration(config)

# Use
logger = get_logger(__name__)
logger.info("Application started", caller_depth=0)

With JSON Logging

config = LoggingConfig(
    level="INFO",
    json_file_name="logs/app.jsonl"
)
LoggerFactory._apply_configuration(config)

Per-Module Levels

config = LoggingConfig(
    level="INFO",
    module_levels={
        "app.database": "DEBUG",
        "app.network": "TRACE"
    }
)
LoggerFactory._apply_configuration(config)

Dedicated JSON Logger

from arlogi import get_json_logger, cleanup_json_logger

audit_logger = get_json_logger("audit", "logs/audit.jsonl")
audit_logger.info("User action", user_id=123)

# Clean up when done
cleanup_json_logger("audit")

Performance Notes

  • Standard log call: ~0.5ฮผs (no attribution)
  • Log with caller_depth: ~1.5ฮผs (stack frame inspection)
  • Deep stack (depth=5): ~3ฮผs (multiple frame walks)

For optimal performance, use caller_depth only when needed for debugging or context tracking.

Testing Integration

Arlogi automatically detects test environments (pytest, unittest) and:

  • Sets default level to DEBUG (instead of INFO)
  • Skips handler setup to prevent double logging
  • Works seamlessly with caplog fixture

No special configuration needed!

Requirements

  • Python: 3.13 or higher
  • Dependencies: rich >= 14.2.0 (automatically installed)

Additional Resources

License

MIT License