python logging（长文讲解）

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战 / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

• 新项目:《从零手撸：仿小红书（微服务架构）》 正在持续爆肝中，基于 Spring Cloud Alibaba + Spring Boot 3.x + JDK 17...，点击查看项目介绍 ;演示链接： http://116.62.199.48:7070 ;
• 《从零手撸：前后端分离博客项目（全栈开发）》 2 期已完结，演示链接： http://116.62.199.48/ ;

截止目前， 星球 内专栏累计输出 90w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 3100+ 小伙伴加入学习 ，欢迎点击围观

前言：日志系统在 Python 开发中的重要性

在软件开发过程中，调试和问题排查是开发者最常面对的挑战之一。当代码规模扩大或系统复杂度提升时，如何高效追踪程序运行状态、定位异常原因便显得尤为重要。Python 的内置模块 logging 正是为解决这一痛点而设计的。与简单粗暴的 print 语句相比，logging 提供了更灵活的记录方式、更丰富的配置选项以及更专业的日志管理能力。本文将通过循序渐进的方式，带领读者从基础概念到高级用法全面掌握这一工具，助力开发者构建更健壮的 Python 应用。

核心概念：理解日志系统的四大支柱

要高效使用 logging 模块，首先需要理解其四大核心概念：日志记录器（Logger）、处理器（Handler）、格式化器（Formatter） 和 过滤器（Filter）。我们可以将它们想象成一个快递公司的运作流程：

• 日志记录器（Logger）：如同快递网点，负责接收开发者发送的“包裹”（日志信息），并决定如何处理这些信息。
• 处理器（Handler）：类似快递分拣中心，决定将日志“包裹”发送到何处（如控制台、文件或网络端口）。
• 格式化器（Formatter）：相当于快递单上的标签，定义日志信息的呈现格式（如时间、日志级别、消息内容）。
• 过滤器（Filter）：如同快递安检，根据特定条件筛选出需要处理的日志条目。

这一比喻帮助开发者快速理解各组件的分工协作关系。

基本使用：从第一个日志记录器开始

步骤 1：创建并配置基础日志记录器

import logging

logger = logging.getLogger("my_logger")

logger.setLevel(logging.DEBUG)

console_handler = logging.StreamHandler()

console_handler.setLevel(logging.INFO)

formatter = logging.Formatter("%(asctime)s - %(levelname)s - %(message)s")

console_handler.setFormatter(formatter)

logger.addHandler(console_handler)

logger.debug("调试信息")
logger.info("程序正常运行")
logger.warning("潜在问题警告")
logger.error("发生错误")
logger.critical("严重错误")

关键点解析：

• 日志级别：从高到低为 CRITICAL > ERROR > WARNING > INFO > DEBUG。通过设置 setLevel()，可以过滤掉低于指定级别的日志。
• 处理器复用性：一个处理器可被多个记录器共享，例如同时输出到文件和控制台。
• 默认行为：未配置时，logging 模块会使用 Python 的默认根记录器，但其默认级别为 WARNING，因此 DEBUG 和 INFO 级别的日志会被忽略。

进阶功能：多处理器与文件日志管理

案例：同时输出到控制台和文件

import logging

logger = logging.getLogger("app_logger")
logger.setLevel(logging.DEBUG)

console_handler = logging.StreamHandler()
console_handler.setLevel(logging.INFO)
console_formatter = logging.Formatter("%(levelname)s: %(message)s")
console_handler.setFormatter(console_formatter)

file_handler = logging.FileHandler("app.log", mode="w")
file_handler.setLevel(logging.DEBUG)
file_formatter = logging.Formatter("%(asctime)s - %(levelname)s - %(message)s")
file_handler.setFormatter(file_formatter)

logger.addHandler(console_handler)
logger.addHandler(file_handler)

logger.debug("系统启动成功")
logger.info("用户登录：user123")
logger.error("数据库连接失败")

实际效果：

• 控制台仅显示 INFO 和 ERROR 级别的日志。
• 文件 app.log 会记录所有 DEBUG 级别及以上的日志，包括时间戳。

文件管理技巧：

• 使用 mode="a"（追加模式）避免覆盖历史日志。
• 当日志文件过大时，可结合 logging.handlers.RotatingFileHandler 实现自动轮转：

from logging.handlers import RotatingFileHandler

file_handler = RotatingFileHandler(
    "app.log",
    maxBytes=1024*1024*5,  # 5MB
    backupCount=3          # 保留3个历史文件
)

高级配置：动态调整与外部配置文件

方法 1：通过代码动态配置

logging.basicConfig(
    filename="dynamic.log",
    filemode="w",
    format="%(name)s - %(levelname)s - %(message)s",
    level=logging.INFO
)

logging.info("配置文件方式记录日志")

方法 2：使用配置文件（logging.conf）

[loggers]
keys=root,simpleExample

[handlers]
keys=consoleHandler

[formatters]
keys=simpleFormatter

[logger_root]
level=DEBUG
handlers=consoleHandler

[logger_simpleExample]
level=INFO
handlers=consoleHandler
qualname=simpleExample
propagate=0

[handler_consoleHandler]
class=StreamHandler
level=ERROR
formatter=simpleFormatter
args=(sys.stdout,)

[formatter_simpleFormatter]
format=%(asctime)s - %(name)s - %(levelname)s - %(message)s
datefmt=

加载配置文件：

import logging.config
import logging

logging.config.fileConfig("logging.conf")
logger = logging.getLogger("simpleExample")
logger.info("通过配置文件初始化日志")

最佳实践：避免常见陷阱与优化建议

陷阱 1：重复创建日志记录器

错误写法：

def my_func():
    logger = logging.getLogger("my_logger")  # 每次创建新实例
    logger.info("函数调用")

正确写法：

logger = logging.getLogger("my_logger")  # 全局唯一实例

def my_func():
    logger.info("函数调用")

陷阱 2：忽略异常日志的上下文

try:
    risky_operation()
except Exception as e:
    logger.error(f"操作失败: {str(e)}")  # 缺少堆栈跟踪

优化后：

try:
    risky_operation()
except Exception as e:
    logger.exception("操作失败")  # 自动记录异常堆栈

优化建议：

• 日志级别策略：生产环境建议设置为 INFO 或 WARNING，开发时使用 DEBUG。
• 异步日志记录：对于高并发场景，可结合 concurrent.futures 或第三方库（如 loguru）实现异步写入。
• 日志命名空间：通过记录器名称（如 app.module.submodule）实现模块化日志管理。

结论：构建可靠日志系统的关键步骤

通过本文的学习，开发者可以掌握以下核心能力：

1. 基础配置：创建记录器、处理器、格式化器并组合使用。
2. 多场景适配：根据需求选择控制台、文件或网络输出方式。
3. 系统化管理：利用配置文件实现集中式日志配置。
4. 问题排查增强：通过异常跟踪、日志轮转等功能提升系统健壮性。

在实际开发中，建议遵循以下流程：

1. 设计日志记录器层级结构。
2. 配置基础日志级别与输出格式。
3. 根据环境（开发/生产）动态调整配置。
4. 定期审查日志文件，优化日志策略。

Python 的 logging 模块如同一把瑞士军刀，其灵活性和扩展性能够满足从简单脚本到复杂分布式系统的日志需求。掌握这一工具，将为开发者构建更可靠、可维护的应用程序提供坚实保障。