python-logging-best-practices
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChinesePython Logging Best Practices
Python日志记录最佳实践
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
在以下场景使用该技能：
- 使用loguru搭建Python日志记录系统
- 配置用于分析的结构化JSONL日志
- 实现日志轮转
- 使用platformdirs实现跨平台日志目录
Overview
概述
Unified reference for Python logging patterns optimized for machine readability (Claude Code analysis) and operational reliability.
针对Python日志记录模式的统一参考，优化了机器可读性（适配Claude Code分析）和运行可靠性。
MANDATORY Best Practices
强制遵循的最佳实践
1. Log Rotation (ALWAYS CONFIGURE)
1. 日志轮转（必须配置）
Prevent unbounded log growth - configure rotation for ALL log files:
python
undefined防止日志无限制增长 - 为所有日志文件配置轮转：
python
undefinedLoguru pattern (recommended for modern scripts)
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
)
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)
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)
)
undefinedfrom logging.handlers import RotatingFileHandler
handler = RotatingFileHandler(
log_path,
maxBytes=100 * 1024 * 1024, # 100MB
backupCount=5 # Keep 5 backups (~500MB max)
)
undefined2. JSONL Format (Machine-Readable)
2. JSONL格式（机器可读）
Use JSONL () for logs that Claude Code or other tools will analyze:
.jsonlpython
undefined将Claude Code或其他工具要分析的日志设置为JSONL（）格式：
.jsonlpython
undefinedOne JSON object per line - jq-parseable
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.{"timestamp": "2026-01-14T12:45:23.456Z", "level": "info", "message": "..."}
{"timestamp": "2026-01-14T12:45:24.789Z", "level": "error", "message": "..."}
**文件扩展名**：始终使用`.jsonl`（不要用`.json`或`.log`）
**验证**：`cat file.jsonl | jq -c .`
**术语说明**：JSONL是标准叫法，等效术语包括NDJSON、JSON Lines。When to Use Which Approach
不同方案的适用场景
| Approach | Use Case | Pros | Cons |
|---|---|---|---|
| Modern scripts, CLI tools | Zero-config, async-safe, built-in rotation | External dependency |
| LaunchAgent daemons, stdlib-only | No dependencies | More setup |
| Rich terminal apps | Beautiful output | Complex setup |
| 方案 | 适用场景 | 优势 | 劣势 |
|---|---|---|---|
| 现代脚本、CLI工具 | 零配置、支持异步、内置日志轮转功能 | 依赖第三方库 |
| LaunchAgent守护进程、仅用标准库 | 无额外依赖 | 配置步骤繁琐 |
| 功能丰富的终端应用 | 输出美观 | 配置复杂 |
Complete Loguru + platformdirs Pattern
完整的Loguru + platformdirs示例
Cross-platform log directory handling with structured JSONL output:
python
#!/usr/bin/env python3实现跨平台日志目录管理及结构化JSONL输出：
python
#!/usr/bin/env python3/// script
/// script
requires-python = ">=3.11"
requires-python = ">=3.11"
dependencies = ["loguru", "platformdirs"]
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 loggerimport 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 loggerUsage
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}
)
undefinedsetup_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}
)
undefinedSemantic Fields Reference
语义字段参考
| Field | Type | Purpose |
|---|---|---|
| ISO 8601 with Z | Event ordering |
| string | debug/info/warning/error/critical |
| string | Module/function name |
| string | What action is being performed |
| string | started/success/failed/skipped |
| UUID4 | Correlation for async operations |
| string | Human-readable description |
| object | Operation-specific metadata |
| object | Quantitative data (counts, durations) |
| object/null | Exception details if failed |
| 字段 | 类型 | 用途 |
|---|---|---|
| ISO 8601带Z后缀 | 事件排序 |
| 字符串 | debug/info/warning/error/critical |
| 字符串 | 模块/函数名 |
| 字符串 | 当前执行的操作 |
| 字符串 | started/success/failed/skipped |
| UUID4 | 异步操作的关联ID |
| 字符串 | 人类可读的描述信息 |
| 对象 | 操作相关的元数据 |
| 对象 | 量化数据（数量、耗时等） |
| 对象/空值 | 操作失败时的异常详情 |
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
- Python logging.handlers - 用于日志轮转的RotatingFileHandler
- platformdirs参考 - 跨平台目录处理
- loguru模式 - Loguru高级配置
- 迁移指南 - 从print()到结构化日志的迁移
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
- 无限制增长的日志 - 始终配置日志轮转
- 用print()记录日志 - 使用结构化日志记录器
- 裸except语句 - 捕获特定异常并记录
- 静默失败 - 抑制异常前先记录错误
- 硬编码路径 - 使用platformdirs实现跨平台兼容
Troubleshooting
故障排查
| Issue | Cause | Solution |
|---|---|---|
| loguru not found | Not installed | Run |
| 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 |
| JSONL parse errors | Malformed log line | Check for unescaped special characters |
| Logs in wrong directory | Using hardcoded path | Use platformdirs.user_log_dir() |
| 问题 | 原因 | 解决方案 |
|---|---|---|
| loguru未找到 | 未安装 | 运行 |
| 日志未显示 | 日志级别设置错误 | 设置级别为DEBUG以排查问题 |
| 日志轮转不生效 | 缺少轮转配置 | 为logger.add()添加rotation参数 |
| platformdirs导入错误 | 未安装 | 运行 |
| JSONL解析错误 | 日志行格式错误 | 检查是否存在未转义的特殊字符 |
| 日志存储目录错误 | 使用了硬编码路径 | 使用platformdirs.user_log_dir() |