当前位置：首页 > news >正文

Python Logging 模块完全指南

news 来源：原创 2025/5/19 8:00:47

1.日志等级详解

2.基础使用方法

日志记录函数

3.日志格式配置

常用格式字段

basicConfig() 快速配置

4.处理器与输出

控制台输出

文件输出

完整示例

5.最佳实践

日志记录建议

6.总结

前言：为什么需要专业的日志记录？

相比简单的 print() 语句，Python 的 logging 模块提供了企业级的日志记录功能，包括多级别日志、灵活格式配置、多种输出目标和线程安全等特性。

1.日志等级详解

Python logging 定义了5个标准日志级别，按严重程度递增排列：

级别	数值	描述	使用场景
DEBUG	10	详细信息，通常仅在调试时使用	变量值、流程跟踪
INFO	20	确认程序按预期运行	服务启动、重要事件
WARNING	30	表示意外情况或潜在问题	磁盘空间不足、API响应慢
ERROR	40	严重错误，程序部分功能失效	数据库连接失败、API调用异常
CRITICAL	50	致命错误，程序可能无法继续运行	系统崩溃、关键资源不可用

默认日志级别：如果不设置日志级别，logging 默认只记录 WARNING 及以上级别的日志。

2.基础使用方法

日志记录函数

logging 模块提供了不同级别的日志记录函数：

logging.debug(msg, *args, **kwargs)
logging.info(msg, *args, **kwargs)
logging.warning(msg, *args, **kwargs)
logging.error(msg, *args, **kwargs)
logging.critical(msg, *args, **kwargs)

这些函数都接受一个字符串消息和可选参数，用于字符串格式化：

logger.info("User %s logged in from %s", username, ip_address)

性能提示：使用 % 格式化而不是 f-string 或 .format() 可以提高性能，因为只有在消息实际需要输出时才会进行格式化。

3.日志格式配置

常用格式字段

logging 使用 Formatter 类来定义日志的输出格式：

基本字段

%(asctime)s - 日志创建时间
%(name)s - 记录器名称
%(levelname)s - 日志级别
%(message)s - 日志消息

调试字段

%(filename)s - 产生日志的文件名
%(lineno)d - 代码行号
%(funcName)s - 函数名
%(thread)d - 线程ID

basicConfig() 快速配置

logging.basicConfig() 是快速配置 logging 模块的便捷方法：

import logginglogging.basicConfig(level=logging.DEBUG,format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',filename='app.log',filemode='a'
)

重要限制：basicConfig() 只能在第一次调用时生效，后续调用不会改变配置。

4.处理器与输出

控制台输出

使用 StreamHandler 可以将日志输出到控制台：

import logginglogger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG)# 创建控制台处理器
console_handler = logging.StreamHandler()
console_handler.setLevel(logging.INFO)  # 控制台只显示INFO及以上# 创建格式器并添加到处理器
formatter = logging.Formatter('%(levelname)s - %(message)s')
console_handler.setFormatter(formatter)# 将处理器添加到记录器
logger.addHandler(console_handler)logger.info("This will appear on console")
logger.debug("This debug message won't appear on console")

文件输出

使用 FileHandler 可以将日志输出到文件：

import logging
from logging.handlers import RotatingFileHandlerlogger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG)# 创建文件处理器（自动滚动）
file_handler = RotatingFileHandler('app.log',maxBytes=1024*1024,  # 1MBbackupCount=5,       # 保留5个备份encoding='utf-8'
)
file_handler.setLevel(logging.DEBUG)# 创建格式器
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
file_handler.setFormatter(formatter)logger.addHandler(file_handler)logger.info("This will be written to the log file")

完整示例

import logging# 创建 logger 对象（建议使用 __name__）
logger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG)  # 设置记录器级别# 创建格式器
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')# 文件处理器（如果文件不存在会自动创建）
fh = logging.FileHandler('api.log', mode='a', encoding='utf-8')
fh.setLevel(logging.DEBUG)
fh.setFormatter(formatter)# 控制台处理器（建议添加）
sh = logging.StreamHandler()
sh.setLevel(logging.DEBUG)
sh.setFormatter(formatter)# 添加处理器（避免重复添加）
if not logger.handlers:logger.addHandler(fh)logger.addHandler(sh)if __name__ == "__main__":logger.debug('----- 调试信息 [debug]-----')logger.info('----- 有用的信息 [info]-----')logger.warning('----- 警告信息 [warning]-----')logger.error('----- 错误信息 [error]-----')logger.critical('----- 严重错误信息 [critical]-----')