Python使用logging搭建工程级日志系统的最佳实践

在日常开发中，日志系统往往被忽视，直到线上出了问题才后悔莫及。今天就来聊聊如何用 Python 的 logging 模块搭建一套工程级的日志系统，从入门到实战，一步到位。

1. 为什么不用 print？

你可能会问，为什么非要上 logging 而不是继续用 print？生产环境需要日志分级、持久化、格式化控制。print 一梭子下去，排查问题时两眼一抹黑，分不清是 info 还是 error，文件没有自动切割，服务重启后日志就丢了。这就像用纸笔记账和用财务软件的区别——小打小闹可以，真上了规模，logging 才是正解。

2. 快速入门：logging 五大组件

理解这五个组件，就掌握了 logging 的核心。Logger 是入口，Handler 管输出，Formatter 管格式，Filter 做筛选，Level 控制严重程度。

3. 一行配置，即插即用

import logging

# 最简配置（同时输出到终端和文件）
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
    datefmt="%Y-%m-%d %H:%M:%S",
    handlers=[
        logging.StreamHandler(),                    # 终端
        logging.FileHandler("app.log", encoding="utf-8"),  # 文件
    ],
)

log = logging.getLogger(__name__)

log.info("服务启动成功")
log.warning("磁盘使用率超过 80%%")
log.error("数据库连接超时", exc_info=True)  # 自动打印堆栈

这段代码几乎能应付 80% 的日常需求。注意 exc_info=True 这个参数，异常发生时自动打印堆栈，比手动 traceback.format_exc() 省事多了。

4. 实用技巧：日志轮转

文件无限增大会撑爆磁盘，用 RotatingFileHandler 自动切割：

from logging.handlers import RotatingFileHandler

handler = RotatingFileHandler(
    "app.log",
    maxBytes=10 * 1024 * 1024,  # 10MB
    backupCount=5,              # 保留 5 个备份
    encoding="utf-8",
)
handler.setFormatter(logging.Formatter(
    "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
))

当文件超过 10MB 时，自动重命名并创建新文件，最多保留 5 个历史备份。这样既不会丢掉历史日志，也不会撑爆磁盘。

5. 按模块化分层

大型项目不要全局一把梭，每个模块独立 Logger：

# utils/db.py
logger = logging.getLogger("app.db")

# utils/http.py
logger = logging.getLogger("app.http")

配合 logging.getLogger("app") 统一配置，子 Logger 继承父配置，省心。这样在日志中就能清晰看到是哪个模块出了问题，定位效率翻倍。

6. 高级：JSON 日志（对接 ELK / 日志平台）

import json
import logging


class JsonFormatter(logging.Formatter):
    def format(self, record: logging.LogRecord) -> str:
        log_obj = {
            "time": self.formatTime(record, self.datefmt),
            "level": record.levelname,
            "logger": record.name,
            "message": record.getMessage(),
        }
        if record.exc_info and record.exc_info[0]:
            log_obj["exception"] = self.formatException(record.exc_info)
        return json.dumps(log_obj, ensure_ascii=False)

如果你在微服务架构中对接 ELK 或 Loki，JSON 格式是标配。结构化的日志方便搜索引擎解析和聚合，搜索、统计、告警都变得异常简单。

7. 避坑指南

这几个坑几乎是每个 Python 开发者都会踩的，尤其是空参 Logger 和重复添加 Handler，记得遇到时回头看看这张表。

8. 开箱即用的模板

import logging
import logging.handlers
import sys
from pathlib import Path


def setup_logger(
    name: str = __name__,
    level: str = "INFO",
    log_file: str | None = None,
) -> logging.Logger:
    logger = logging.getLogger(name)
    if logger.handlers:
        return logger  # 防止重复添加

    logger.setLevel(getattr(logging, level.upper(), logging.INFO))

    fmt = logging.Formatter(
        "%(asctime)s [%(levelname)s] %(name)s:%(lineno)d: %(message)s"
    )

    # 终端 Handler（始终输出 >= WARNING）
    console = logging.StreamHandler(sys.stdout)
    console.setLevel(logging.WARNING)
    console.setFormatter(fmt)
    logger.addHandler(console)

    # 文件 Handler 带轮转（输出全部级别）
    if log_file:
        Path(log_file).parent.mkdir(parents=True, exist_ok=True)
        handler = logging.handlers.RotatingFileHandler(
            log_file, maxBytes=10 << 20, backupCount=5, encoding="utf-8"
        )
        handler.setLevel(logging.DEBUG)
        handler.setFormatter(fmt)
        logger.addHandler(handler)

    return logger


# 使用
log = setup_logger("my_app", level="DEBUG", log_file="logs/my_app.log")
log.info("✅ Logger 初始化完成")

这段代码可以直接复制到你的项目里，稍作修改就能用。它包含了终端输出（只显示 WARNING 及以上）、文件轮转（10MB 切割、保留 5 份）、防重复 Handler 等最佳实践。

小结

• 小脚本：logging.basicConfig 一行搞定
• 中型项目：模块化 Logger + 文件轮转
• 大型/微服务：JSON 格式 + JSON 收集至 ELK/Loki

从现在开始，所有 Python 项目都值得用 logging 替代 print，这是专业开发者与新手的分水岭。