python-logging-best-practices

# Python Logging Best Practices

## 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:

```python
# 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:

```python
# 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