Python logging搭建工程级日志系统实战指南

脚本专家

很多Python开发者习惯用print调试，但到了生产环境，print无法控制日志级别、持久化和格式化，排查问题非常困难。logging模块是Python标准库提供的日志系统，支持分级输出、文件记录和格式自定义，是替代print的正确选择。

## 快速入门：五大组件

logging模块由五个核心组件构成：Logger（日志入口，负责分级记录）、Handler（输出目的地，如文件或终端）、Formatter（定义日志格式）、Filter（按条件过滤日志）、Level（日志级别，从低到高为DEBUG、INFO、WARNING、ERROR、CRITICAL）。理解这些组件有助于灵活配置日志系统。

## 一行配置即插即用

对于小型项目，使用basicConfig快速完成配置，同时输出到终端和文件：

2. import logging
3. logging.basicConfig(
4.     level=logging.INFO,
5.     format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
6.     datefmt="%Y-%m-%d %H:%M:%S",
7.     handlers=[
8.         logging.StreamHandler(),
9.         logging.FileHandler("app.log", encoding="utf-8"),
10.     ],
11. )
12. log = logging.getLogger(__name__)
13. log.info("服务启动成功")
14. log.warning("磁盘使用率超过 80%%")
15. log.error("数据库连接超时", exc_info=True)  # 自动打印堆栈

复制代码

注意：exc_info=True可以在ERROR级别自动输出异常堆栈，便于定位问题。

## 日志轮转防止磁盘撑爆

文件日志无限增长会耗尽磁盘空间。使用RotatingFileHandler按大小自动切割：

2. from logging.handlers import RotatingFileHandler
3. handler = RotatingFileHandler(
4.     "app.log",
5.     maxBytes=10 * 1024 * 1024,  # 10MB
6.     backupCount=5,  # 保留5个备份
7.     encoding="utf-8",
8. )
9. handler.setFormatter(logging.Formatter(
10.     "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
11. ))

复制代码

当文件达到10MB时，handler自动重命名并创建新文件，保留最近5个历史备份。

## 按模块分层管理

大型项目不应使用单一全局Logger，应为每个模块创建独立Logger，方便定位日志来源：

2. # utils/db.py
3. logger = logging.getLogger("app.db")
5. # utils/http.py
6. logger = logging.getLogger("app.http")

复制代码

根Logger（如"app"）统一配置后，子Logger自动继承，无需重复设置Handler和格式。

## 高级：输出JSON格式日志

对接ELK等日志平台时，JSON格式更易解析。自定义Formatter将日志转换为JSON字符串：

2. import json
3. import logging
5. class JsonFormatter(logging.Formatter):
6.     def format(self, record: logging.LogRecord) -> str:
7.         log_obj = {
8.             "time": self.formatTime(record, self.datefmt),
9.             "level": record.levelname,
10.             "logger": record.name,
11.             "message": record.getMessage(),
12.         }
13.         if record.exc_info and record.exc_info[0]:
14.             log_obj["exception"] = self.formatException(record.exc_info)
15.         return json.dumps(log_obj, ensure_ascii=False)

复制代码

将JsonFormatter设置给Handler后，每行日志输出一个合规的JSON对象。

## 避坑指南

- 不要使用空参getLogger()，应传入__name__以明确模块来源。
- 消息格式优先使用"%s" % user的惰性求值，避免不必要的格式化开销。
- 重复添加Handler会导致日志重复输出，可在添加前检查logger.handlers是否为空。
- 文件路径包含中文时，务必指定FileHandler的encoding="utf-8"防止乱码。
- 生产环境日志级别应通过环境变量控制：getattr(logging, os.getenv("LOG_LEVEL", "INFO"))。

## 开箱即用模板

以下函数封装了终端（仅WARNING及以上）和文件（含轮转）的完整配置，适合直接集成到项目中：

2. import logging
3. import logging.handlers
4. import sys
5. from pathlib import Path
7. def setup_logger(
8.     name: str = __name__,
9.     level: str = "INFO",
10.     log_file: str | None = None,
11. ) -> logging.Logger:
12.     logger = logging.getLogger(name)
13.     if logger.handlers:
14.         return logger
15.     logger.setLevel(getattr(logging, level.upper(), logging.INFO))
16.     fmt = logging.Formatter(
17.         "%(asctime)s [%(levelname)s] %(name)s:%(lineno)d: %(message)s"
18.     )
19.     console = logging.StreamHandler(sys.stdout)
20.     console.setLevel(logging.WARNING)
21.     console.setFormatter(fmt)
22.     logger.addHandler(console)
23.     if log_file:
24.         Path(log_file).parent.mkdir(parents=True, exist_ok=True)
25.         handler = logging.handlers.RotatingFileHandler(
26.             log_file, maxBytes=10 << 20, backupCount=5, encoding="utf-8"
27.         )
28.         handler.setLevel(logging.DEBUG)
29.         handler.setFormatter(fmt)
30.         logger.addHandler(handler)
31.     return logger
33. log = setup_logger("my_app", level="DEBUG", log_file="logs/my_app.log")
34. log.info("Logger 初始化完成")

复制代码

## 总结

轻量脚本用basicConfig，中型项目推荐模块化Logger+文件轮转，微服务场景输出JSON格式对接ELK。告别print是Python开发专业化的第一步。

热心网友7

非常实用，感谢分享！我之前一直用 basicConfig 凑合，但项目大了之后确实遇到日志重复输出和文件无限增长的问题。你提到的“在添加 handler 前检查 handlers 是否为空”这点特别关键，之前踩过坑，配置了根 logger 后又给子 logger 加 handler，结果每条日志重复打印好几遍。另外 JSONFormatter 那个例子很实用，对接 ELK 时可以直接拿来用，省了自己从头造轮子的时间。想问一下，如果项目里同时有同步和异步代码，logging 的 handler 需要额外考虑线程安全吗？还是默认就是线程安全的？

热心网友7

非常感谢分享这么详细的日志系统实战指南！从basicConfig快速上手到自定义JSON Formatter，再到项目级的分层管理和轮转配置，每一步都讲得很清晰，而且避坑指南里的常见错误正是新手容易踩的坑。我已经把开箱即用模板收藏了，直接复用能省不少事。特别是通过环境变量控制日志级别这点，在容器化部署时非常有用。再次感谢！

热心网友7

这篇帖子非常实用，从基础组件到生产环境的注意事项都讲得很透彻。特别是避坑指南里提到的重复添加Handler、惰性求值和使用`__name__`这些细节，确实是新手容易踩坑的地方。JSON格式Formatter和开箱即用模板也很有参考价值，直接复制就能集成到项目中。感谢分享。