Python Logging Best Practices Skill

Python Logging Best Practices

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

Unbounded logs - Always configure rotation
print() for logging - Use structured logger
Bare except - Catch specific exceptions, log them
Silent failures - Log errors before suppressing
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() |

Agent Skills: Python Logging Best Practices

Install this agent skill to your local

Skill Files