Python Logging Best Practices

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use This Skill

Use this skill when:

• Setting up Python logging with loguru
• Configuring structured JSONL logging for analysis
• Implementing log rotation
• Using platformdirs for cross-platform log directories

Overview

Unified reference for Python logging patterns optimized for machine readability (Claude Code analysis) and operational reliability.

MANDATORY Best Practices

1. Log Rotation (ALWAYS CONFIGURE)

Prevent unbounded log growth - configure rotation for ALL log files:

# Loguru pattern (recommended for modern scripts)
from loguru import logger

logger.add(
    log_path,
    rotation="10 MB",      # Rotate at 10MB
    retention="7 days",    # Keep 7 days
    compression="gz"       # Compress old logs
)

# RotatingFileHandler pattern (stdlib-only)
from logging.handlers import RotatingFileHandler

handler = RotatingFileHandler(
    log_path,
    maxBytes=100 * 1024 * 1024,  # 100MB
    backupCount=5                 # Keep 5 backups (~500MB max)
)

2. JSONL Format (Machine-Readable)

Use JSONL (.jsonl) for logs that Claude Code or other tools will analyze:

# One JSON object per line - jq-parseable
{"timestamp": "2026-01-14T12:45:23.456Z", "level": "info", "message": "..."}
{"timestamp": "2026-01-14T12:45:24.789Z", "level": "error", "message": "..."}

File extension: Always use .jsonl (not .json or .log)

Validation: cat file.jsonl | jq -c .

Terminology: JSONL is canonical. Equivalent terms: NDJSON, JSON Lines.

When to Use Which Approach

Approach	Use Case	Pros	Cons
loguru	Modern scripts, CLI tools	Zero-config, async-safe, built-in rotation	External dependency
RotatingFileHandler	LaunchAgent daemons, stdlib-only	No dependencies	More setup
logger_setup.py	Rich terminal apps	Beautiful output	Complex setup

Complete Loguru + platformdirs Pattern

Cross-platform log directory handling with structured JSONL output:

#!/usr/bin/env python3
# /// script
# requires-python = ">=3.11"
# dependencies = ["loguru", "platformdirs"]
# ///

import json
import sys
from pathlib import Path
from uuid import uuid4

import platformdirs
from loguru import logger


def json_formatter(record) -> str:
    """JSONL formatter for Claude Code analysis."""
    log_entry = {
        "timestamp": record["time"].strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z",
        "level": record["level"].name.lower(),
        "component": record["function"],
        "operation": record["extra"].get("operation", "unknown"),
        "operation_status": record["extra"].get("status", None),
        "trace_id": record["extra"].get("trace_id"),
        "message": record["message"],
        "context": {k: v for k, v in record["extra"].items()
                   if k not in ("operation", "status", "trace_id", "metrics")},
        "metrics": record["extra"].get("metrics", {}),
        "error": None
    }

    if record["exception"]:
        exc_type, exc_value, _ = record["exception"]
        log_entry["error"] = {
            "type": exc_type.__name__ if exc_type else "Unknown",
            "message": str(exc_value) if exc_value else "Unknown error",
        }

    return json.dumps(log_entry)


def setup_logger(app_name: str = "my-app"):
    """Configure Loguru for machine-readable JSONL output."""
    logger.remove()

    # Console output (JSONL to stderr)
    logger.add(sys.stderr, format=json_formatter, level="INFO")

    # Cross-platform log directory
    # macOS: ~/Library/Logs/{app_name}/
    # Linux: ~/.local/state/{app_name}/log/
    log_dir = Path(platformdirs.user_log_dir(
        appname=app_name,
        ensure_exists=True
    ))

    # File output with rotation
    logger.add(
        str(log_dir / f"{app_name}.jsonl"),
        format=json_formatter,
        rotation="10 MB",
        retention="7 days",
        compression="gz",
        level="DEBUG"
    )

    return logger


# Usage
setup_logger("my-app")
trace_id = str(uuid4())

logger.info(
    "Operation started",
    operation="my_operation",
    status="started",
    trace_id=trace_id
)

logger.info(
    "Operation complete",
    operation="my_operation",
    status="success",
    trace_id=trace_id,
    metrics={"duration_ms": 150, "items_processed": 42}
)

Semantic Fields Reference

Field	Type	Purpose
timestamp	ISO 8601 with Z	Event ordering
level	string	debug/info/warning/error/critical
component	string	Module/function name
operation	string	What action is being performed
operation_status	string	started/success/failed/skipped
trace_id	UUID4	Correlation for async operations
message	string	Human-readable description
context	object	Operation-specific metadata
metrics	object	Quantitative data (counts, durations)
error	object/null	Exception details if failed

Related Resources

• Python logging.handlers - RotatingFileHandler for log rotation
• platformdirs reference - Cross-platform directories
• loguru patterns - Advanced loguru configuration
• migration guide - From print() to structured logging

Anti-Patterns to Avoid

1. Unbounded logs - Always configure rotation
2. print() for logging - Use structured logger
3. Bare except - Catch specific exceptions, log them
4. Silent failures - Log errors before suppressing
5. Hardcoded paths - Use platformdirs for cross-platform

---

Troubleshooting

Issue	Cause	Solution
loguru not found	Not installed	Run uv add loguru
Logs not appearing	Wrong log level	Set level to DEBUG for troubleshooting
Log rotation not working	Missing rotation config	Add rotation param to logger.add()
platformdirs import error	Not installed	Run uv add platformdirs
JSONL parse errors	Malformed log line	Check for unescaped special characters
Logs in wrong directory	Using hardcoded path	Use platformdirs.user_log_dir()

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure.
2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.