Python 库手册：logging 日记记录模块

Python 的 logging 模块是官方推荐的日志记录工具，适用于小型脚本和大型系统。它提供了灵活统一的日志处理机制，可将日志信息输出到终端、文件、网络服务等多种媒介，支持日志等级分类、格式化输出、日志轮换和多模块共享。

常见应用场景：

（1）程序运行时的信息跟踪（debug、info、error 等）。

（2）错误记录与异常分析（尤其用于线上系统）。

（3）多模块项目的统一日志管理。

（4）日志文件的自动轮换（配合 handlers）。

（5）跨模块或多线程日志追踪。

◆ ◆ ◆

核心概念

1、日志等级（Log Levels）

日志分为五个主要等级，按严重程度升序排列：

DEBUG：最详细的信息，通常用于调试。

INFO：普通运行信息。

WARNING：警告，但程序还能继续运行。

ERROR：错误，程序部分功能可能失败。

CRITICAL：严重错误，程序可能无法继续运行。

2. 四大核心组件

Logger：记录器，用于产生日志。通常用 logging.getLogger(name) 获取。

Handler：处理器，控制日志输出位置（终端、文件、邮件等）。

Formatter：格式器，定义日志内容的输出格式。

Filter：过滤器，用于细粒度地控制日志输出内容。

◆ ◆ ◆

应用举例

例 1：最简单用法（打印 INFO 级别日志）

import logging

logging.basicConfig(level=logging.INFO)
logging.info("程序启动成功")

例 2：设置日志格式和输出文件

import logging

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

logging.debug("调试信息")
logging.error("发生错误")

例 3：使用 Logger 对象与多个 Handler

import logging

# 创建 Logger
logger = logging.getLogger('myapp')
logger.setLevel(logging.DEBUG)

# 控制台输出
console_handler = logging.StreamHandler()
console_handler.setLevel(logging.INFO)

# 文件输出
file_handler = logging.FileHandler('myapp.log')
file_handler.setLevel(logging.WARNING)

# 日志格式
formatter = logging.Formatter('%(name)s - %(levelname)s - %(message)s')
console_handler.setFormatter(formatter)
file_handler.setFormatter(formatter)

# 添加 Handler
logger.addHandler(console_handler)
logger.addHandler(file_handler)

# 测试输出
logger.debug("调试")
logger.info("普通信息")
logger.warning("警告")
logger.error("错误")

例 4：通过异常信息记录日志

import logging

logging.basicConfig(level=logging.ERROR)

try:
    result = 10 / 0
except Exception as e:
    logging.exception("捕获到异常")  # 自动附带 traceback

例 5：日志轮换（RotatingFileHandler）

import logging
from logging.handlers import RotatingFileHandler

logger = logging.getLogger("rotate")
logger.setLevel(logging.INFO)

# 最大 1MB，最多保留 3 个文件
handler = RotatingFileHandler("rotate.log", maxBytes=1_000_000, backupCount=3)
formatter = logging.Formatter('%(asctime)s - %(message)s')
handler.setFormatter(formatter)

logger.addHandler(handler)

logger.info("这是循环日志测试")

◆ ◆ ◆

常用函数速览

basicConfig(**kwargs)

快速配置日志系统（适用于简单场景）。

参数：

filename：日志输出文件名（若设定则写入文件）

level：日志级别，如 logging.INFO

format：日志格式字符串

filemode：文件模式，如 'w'、'a'

返回：无返回，直接配置全局日志系统

getLogger(name=None)

获取指定名称的 Logger 对象，便于模块内独立使用。

参数：name 为日志器名称，None 为 root logger

返回：Logger 实例，可进行后续调用

log(level, msg, *args)

通用日志方法，手动传入日志级别。

参数：

level：整数形式的日志级别，如 logging.WARNING

msg：消息字符串，支持 %s 占位符格式化

返回：无返回

debug(msg) / info(msg) / warning(msg) / error(msg) / critical(msg)

按不同级别输出日志。

参数：msg 为日志内容

返回：无返回，输出日志

exception(msg)

在 except 块中使用，自动输出堆栈信息。

参数：msg 为日志内容

返回：无返回，相当于 error() + traceback 信息

◆ ◆ ◆

补充说明

1、basicConfig() 只会在首次调用时生效，之后调用将被忽略（除非重启解释器）。

2、实际项目中推荐使用 getLogger() 创建多个模块级 Logger。

3、配置可通过代码或使用 dictConfig/fileConfig 实现更复杂的方案。

4、RotatingFileHandler 和 TimedRotatingFileHandler 是生产环境常用文件日志方案。

5、可通过 Logger.propagate = False 阻止日志向上级传播。

“点赞有美意，赞赏是鼓励”