Python 日志与结构化日志实战

发布于 约 12 分钟

print 调试法在生产环境完全不够用。专业的日志系统需要分级、轮转、结构化，还要能被 ELK 等日志平台采集分析。本文讲清 Python logging 的正确姿势。

Python 日志配图：深蓝色背景上分层日志流通过发光管线连接各层节点，扁平科技插画
结构化日志：让机器和人都能读

一、日志级别

Python logging 有五个标准级别：DEBUG（调试）、INFO（信息）、WARNING（警告）、ERROR（错误）、CRITICAL（严重）。生产环境通常设为 INFO，开发环境设为 DEBUG。

级别数值用途
DEBUG10详细调试信息
INFO20正常运行事件
WARNING30潜在问题警告
ERROR40功能失败
CRITICAL50系统崩溃

二、基础配置

import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
    datefmt="%Y-%m-%d %H:%M:%S"
)

logger = logging.getLogger(__name__)
logger.info("服务启动")
logger.warning("磁盘空间不足")
logger.error("数据库连接失败")

三、日志轮转

from logging.handlers import RotatingFileHandler

handler = RotatingFileHandler(
    "app.log",
    maxBytes=10 * 1024 * 1024,  # 10MB
    backupCount=5,              # 保留 5 个历史文件
    encoding="utf-8"
)

logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)
logger.addHandler(handler)
为什么要轮转：不做轮转，日志文件会无限增长撑爆磁盘。RotatingFileHandler 在达到大小上限后自动切分旧文件。

四、结构化 JSON 日志

pip install python-json-logger
from pythonjsonlogger import jsonlogger

handler = logging.StreamHandler()
formatter = jsonlogger.JsonFormatter(
    "%(asctime)s %(levelname)s %(name)s %(message)s"
)
handler.setFormatter(formatter)

logger = logging.getLogger()
logger.addHandler(handler)
logger.setLevel(logging.INFO)

# 输出变成 JSON：
# {"asctime": "2026-10-25 10:00:00", "levelname": "INFO",
#  "name": "app", "message": "用户登录成功"}
logger.info("用户登录成功", extra={"user_id": 123, "ip": "192.168.1.1"})

五、多模块日志

# utils.py
import logging
logger = logging.getLogger(__name__)

# main.py
import logging.config
from utils import some_function

# 在入口统一配置
logging.config.dictConfig({
    "version": 1,
    "disable_existing_loggers": False,
    "formatters": {
        "standard": {
            "format": "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
        }
    },
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
            "formatter": "standard"
        }
    },
    "root": {"handlers": ["console"], "level": "INFO"}
})

六、最佳实践

第一，不要用 print 代替日志。print 没有级别、没有时间戳、不能分级过滤。第二，日志里打上下文信息：用户 ID、请求 ID、耗时，方便排查问题。第三，异常日志用 logger.exception()，它会自动带上堆栈信息。

七、总结

Python 日志三步：用 logging 模块配好级别和格式、用 RotatingFileHandler 做日志轮转、用 JSON 格式输出方便日志平台采集。记住：日志是给未来排查问题的自己看的，多打上下文信息。

延伸阅读