Configuration Guide¶

Comprehensive guide to configuring Ezpl logging framework.

Overview¶

Ezpl provides flexible configuration management through multiple sources with a clear priority order:

Direct arguments to Ezpl()
Environment variables (EZPL_* prefix)
Configuration file (~/.ezpl/config.json)
Default values

Configuration Sources¶

1. Direct Arguments (Highest Priority)¶

Pass configuration directly to the Ezpl() constructor:

from ezplog import Ezpl

ezpl = Ezpl(
    log_file="app.log",
    log_level="DEBUG",
    printer_level="INFO",
    file_logger_level="DEBUG",
    log_rotation="10 MB",
    log_retention="7 days",
    log_compression="zip",
    indent_step=3,
    indent_symbol=">",
    base_indent_symbol="~"
)

Available Parameters:

Parameter	Type	Description	Default
`log_file`	`str \\| Path`	Log file path	`"ezpl.log"`
`log_level`	`str`	Global log level	`"INFO"`
`printer_level`	`str`	Console level	`"INFO"`
`file_logger_level`	`str`	File level	`"INFO"`
`log_rotation`	`str`	Rotation setting	`None`
`log_retention`	`str`	Retention period	`None`
`log_compression`	`str`	Compression format	`None`
`indent_step`	`int`	Indentation step	`3`
`indent_symbol`	`str`	Indent symbol	`">"`
`base_indent_symbol`	`str`	Base indent symbol	`"~"`

2. Environment Variables¶

Set environment variables with the EZPL_ prefix:

Unix/Linux/macOS:

export EZPL_LOG_LEVEL=DEBUG
export EZPL_LOG_FILE=app.log
export EZPL_PRINTER_LEVEL=INFO
export EZPL_FILE_LOGGER_LEVEL=DEBUG
export EZPL_LOG_ROTATION="10 MB"
export EZPL_LOG_RETENTION="7 days"
export EZPL_LOG_COMPRESSION=zip
export EZPL_INDENT_STEP=3
export EZPL_INDENT_SYMBOL=">"
export EZPL_BASE_INDENT_SYMBOL="~"

Windows:

set EZPL_LOG_LEVEL=DEBUG
set EZPL_LOG_FILE=app.log
set EZPL_PRINTER_LEVEL=INFO
set EZPL_FILE_LOGGER_LEVEL=DEBUG
set EZPL_LOG_ROTATION=10 MB
set EZPL_LOG_RETENTION=7 days
set EZPL_LOG_COMPRESSION=zip
set EZPL_INDENT_STEP=3
set EZPL_INDENT_SYMBOL=>
set EZPL_BASE_INDENT_SYMBOL=~

Using CLI:

ezpl config set log_level DEBUG --env
ezpl config set log_rotation "10 MB" --env

Available Environment Variables:

Variable	Description	Default
`EZPL_LOG_LEVEL`	Global log level	`INFO`
`EZPL_LOG_FILE`	Log file name	`ezpl.log`
`EZPL_LOG_DIR`	Log directory	Platform-specific
`EZPL_PRINTER_LEVEL`	Console level	`INFO`
`EZPL_FILE_LOGGER_LEVEL`	File level	`INFO`
`EZPL_LOG_ROTATION`	Rotation setting	`None`
`EZPL_LOG_RETENTION`	Retention period	`None`
`EZPL_LOG_COMPRESSION`	Compression format	`None`
`EZPL_INDENT_STEP`	Indentation step	`3`
`EZPL_INDENT_SYMBOL`	Indent symbol	`>`
`EZPL_BASE_INDENT_SYMBOL`	Base indent symbol	`~`
`EZPL_LOG_FORMAT`	Log format string	Default format

3. Configuration File¶

Create ~/.ezpl/config.json:

{
  "log-level": "INFO",
  "log-file": "ezpl.log",
  "printer-level": "INFO",
  "file-logger-level": "DEBUG",
  "log-rotation": "10 MB",
  "log-retention": "7 days",
  "log-compression": "zip",
  "indent-step": 3,
  "indent-symbol": ">",
  "base-indent-symbol": "~"
}

Creating Configuration:

from ezplog import Ezpl

# Initialize with desired settings
ezpl = Ezpl(
    log_level="DEBUG",
    log_rotation="10 MB"
)

# Save to configuration file
config = ezpl.get_config()
config.save()

Or using CLI:

ezpl config set log_level DEBUG
ezpl config set log_rotation "10 MB"

4. Default Values¶

If no configuration is provided, Ezpl uses these defaults:

DEFAULT_LOG_LEVEL = "INFO"
DEFAULT_LOG_FILE = "ezpl.log"
DEFAULT_PRINTER_LEVEL = "INFO"
DEFAULT_FILE_LOGGER_LEVEL = "INFO"
DEFAULT_INDENT_STEP = 3
DEFAULT_INDENT_SYMBOL = ">"
DEFAULT_BASE_INDENT_SYMBOL = "~"

Log Levels¶

Available log levels (case-insensitive):

Level	Usage	Console Color
`DEBUG`	Debugging information	Cyan
`INFO`	Informational messages	Blue
`SUCCESS`	Success operations	Green
`WARNING`	Warning messages	Yellow
`ERROR`	Error messages	Red
`CRITICAL`	Critical errors	Magenta on red

Setting Levels:

from ezplog import Ezpl

ezpl = Ezpl()

# Global level (affects both)
ezpl.set_level("DEBUG")

# Specific levels
ezpl.set_printer_level("INFO")   # Console
ezpl.set_logger_level("DEBUG")   # File

Log Rotation¶

Configure automatic log file rotation:

Size-Based Rotation¶

ezpl = Ezpl(log_rotation="10 MB")
ezpl = Ezpl(log_rotation="500 KB")
ezpl = Ezpl(log_rotation="1 GB")

Time-Based Rotation¶

# Daily at midnight
ezpl = Ezpl(log_rotation="00:00")

# Daily at specific time
ezpl = Ezpl(log_rotation="12:00")

# Every X hours/days/weeks
ezpl = Ezpl(log_rotation="12 hours")
ezpl = Ezpl(log_rotation="1 day")
ezpl = Ezpl(log_rotation="1 week")

Rotation Examples¶

Setting	Behavior
`"10 MB"`	Rotate when file reaches 10 MB
`"500 KB"`	Rotate when file reaches 500 KB
`"1 GB"`	Rotate when file reaches 1 GB
`"00:00"`	Rotate daily at midnight
`"12:00"`	Rotate daily at noon
`"12 hours"`	Rotate every 12 hours
`"1 day"`	Rotate every day
`"1 week"`	Rotate every week

Log Retention¶

Configure how long to keep rotated log files:

Time-Based Retention¶

ezpl = Ezpl(log_retention="7 days")
ezpl = Ezpl(log_retention="1 week")
ezpl = Ezpl(log_retention="1 month")

Count-Based Retention¶

ezpl = Ezpl(log_retention="10 files")
ezpl = Ezpl(log_retention="20 files")

Retention Examples¶

Setting	Behavior
`"7 days"`	Keep logs for 7 days
`"1 week"`	Keep logs for 1 week
`"1 month"`	Keep logs for 1 month
`"30 days"`	Keep logs for 30 days
`"10 files"`	Keep last 10 rotated files
`"20 files"`	Keep last 20 rotated files

Log Compression¶

Compress rotated log files:

# ZIP compression
ezpl = Ezpl(log_compression="zip")

# GZIP compression
ezpl = Ezpl(log_compression="gz")

# TAR.GZ compression
ezpl = Ezpl(log_compression="tar.gz")

Compression Formats:

Format	Extension	Compression
`"zip"`	`.zip`	ZIP
`"gz"`	`.gz`	GZIP
`"tar.gz"`	`.tar.gz`	TAR + GZIP

Complete Configuration Example¶

from ezplog import Ezpl

# Production configuration
ezpl = Ezpl(
    log_file="/var/log/myapp/app.log",
    log_level="INFO",
    printer_level="WARNING",      # Less verbose console
    file_logger_level="DEBUG",    # Detailed file logs
    log_rotation="10 MB",          # Rotate at 10 MB
    log_retention="30 days",       # Keep 30 days
    log_compression="gz"           # GZIP compress old logs
)

Runtime Reconfiguration¶

Using configure()¶

from ezplog import Ezpl

ezpl = Ezpl()

# Reconfigure at runtime
ezpl.configure(
    printer_level="DEBUG",
    logger_level="INFO",
    log_rotation="5 MB"
)

Using set_level()¶

ezpl = Ezpl()

# Change levels dynamically
ezpl.set_level("DEBUG")
ezpl.set_printer_level("INFO")
ezpl.set_logger_level("ERROR")

Reloading Configuration¶

ezpl = Ezpl()

# Reload from file and environment
ezpl.reload_config()

Configuration Manager¶

Access the configuration manager directly:

from ezplog import Ezpl

ezpl = Ezpl()
config = ezpl.get_config()

# Get values
log_level = config.get_log_level()
log_file = config.get_log_file()

# Set values
config.set("log-level", "DEBUG")
config.set("log-rotation", "10 MB")

# Save to file
config.save()

# Get all configuration
all_config = config.get_all()

# Reset to defaults
config.reset_to_defaults()

Configuration Locking¶

Lock the configuration after initialization to prevent any library from reconfiguring Ezpl:

from ezplog import Ezpl

# Option 1: lock immediately at initialization (recommended)
ezpl = Ezpl(log_file="app.log", lock_config=True)
token = Ezpl._config_lock_token  # save if you need to unlock later

# Option 2: lock manually after initialization
ezpl = Ezpl(log_file="app.log")
token = Ezpl.lock_config()  # returns a token string

# Check lock state
print(Ezpl.is_locked())  # True

# Any configure() or set_level() call while locked emits a UserWarning
# and has no effect.
ezpl.set_level("DEBUG")       # UserWarning — silently ignored
ezpl.configure(level="DEBUG")  # UserWarning — silently ignored

# Unlock when needed (token must match exactly)
success = Ezpl.unlock_config(token)  # True if token matches

App vs Library Pattern¶

The recommended pattern is: the application configures and locks, libraries use lib mode passively.

# In the application entrypoint — configure once, lock immediately
from ezplog import Ezpl

ezpl = Ezpl(
    log_file="app.log",
    log_level="INFO",
    intercept_stdlib=True,  # capture library stdlib loggers
    lock_config=True,       # prevent any library from reconfiguring
)
ezpl.info("Application started")

# In library code — use lib_mode, never touch Ezpl directly
from ezplog.lib_mode import get_logger, get_printer

log = get_logger(__name__)
printer = get_printer()

def run() -> None:
    log.info("Library running")       # forwarded if app uses intercept_stdlib=True
    printer.success("Library ready")  # forwarded once app initialized Ezpl

Guideline:

Libraries should use lib_mode and never call Ezpl() directly.
The application entrypoint is the sole owner of Ezpl configuration.

Environment-Specific Configuration¶

Development¶

import os

if os.getenv("ENV") == "development":
    ezpl = Ezpl(
        log_level="DEBUG",
        printer_level="DEBUG",
        file_logger_level="DEBUG"
    )
else:
    ezpl = Ezpl(
        log_level="INFO",
        printer_level="WARNING",
        file_logger_level="INFO"
    )

Using Environment Variables¶

# Development
export ENV=development
export EZPL_LOG_LEVEL=DEBUG

# Production
export ENV=production
export EZPL_LOG_LEVEL=INFO
export EZPL_PRINTER_LEVEL=WARNING

Configuration Export¶

Export configuration as environment variables script:

from ezplog import Ezpl

ezpl = Ezpl(log_level="DEBUG", log_rotation="10 MB")
config = ezpl.get_config()

# Export for Unix
config.export_to_script("env.sh", platform="unix")

# Export for Windows
config.export_to_script("env.bat", platform="windows")

Or using CLI:

ezpl config export --output env.sh --platform unix
ezpl config export --output env.bat --platform windows

Generated scripts:

# env.sh (Unix)
export EZPL_LOG_LEVEL="DEBUG"
export EZPL_LOG_FILE="ezpl.log"
export EZPL_LOG_ROTATION="10 MB"

# env.bat (Windows)
set EZPL_LOG_LEVEL=DEBUG
set EZPL_LOG_FILE=ezpl.log
set EZPL_LOG_ROTATION=10 MB

Best Practices¶

1. Use Configuration File for Defaults¶

Create ~/.ezpl/config.json with sensible defaults for your environment.

2. Use Environment Variables for Environment-Specific Settings¶

Set environment variables in your deployment environment (development, staging, production).

3. Use Direct Arguments for Application-Specific Settings¶

Pass specific configuration when initializing Ezpl in your application.

4. Separate Console and File Levels¶

ezpl = Ezpl(
    printer_level="WARNING",   # Less verbose console
    file_logger_level="DEBUG"  # Detailed file logs
)

5. Configure Rotation and Retention¶

ezpl = Ezpl(
    log_rotation="10 MB",
    log_retention="30 days",
    log_compression="gz"
)

6. Use Configuration Locking at Application Startup¶

# In application entrypoint — lock after configuring
from ezplog import Ezpl

ezpl = Ezpl(log_file="app.log", log_level="INFO", lock_config=True)
token = Ezpl._config_lock_token  # store if you need to unlock later

# Libraries using lib_mode are not affected — they forward output transparently

7. Document Your Configuration¶

{
  "log-level": "INFO",
  "log-rotation": "10 MB",
  "log-retention": "30 days",
  "log-compression": "gz"
}

Troubleshooting¶

Configuration Not Applied¶

Check configuration priority order
Verify environment variables are set
Check config file location (~/.ezpl/config.json)
Use ezpl config show to see current configuration

Environment Variables Not Working¶

# Verify variables are set
echo $EZPL_LOG_LEVEL  # Unix
echo %EZPL_LOG_LEVEL%  # Windows

# Check in Python
import os
print(os.getenv("EZPL_LOG_LEVEL"))

Configuration File Not Found¶

from pathlib import Path

config_path = Path.home() / ".ezpl" / "config.json"
print(f"Config file: {config_path}")
print(f"Exists: {config_path.exists()}")

Rotation Not Working¶

Verify rotation setting format:

# Correct
ezpl = Ezpl(log_rotation="10 MB")

# Incorrect
ezpl = Ezpl(log_rotation="10MB")  # Missing space

Need Help?¶

Issues: GitHub Issues
Repository: https://github.com/neuraaak/ezplog