一、基础知识

print 的问题在于:所有信息一视同仁,无法关掉调试信息,也无法写到文件、带上时间和模块名。标准库 logging 用四个角色解决这些问题。

  • Logger(记录器):你写代码时调用的对象,如 logger.info("...")。通常用 logging.getLogger(__name__) 按模块命名,便于按模块控制。
  • Handler(处理器):决定日志往哪儿去,比如控制台 StreamHandler、文件 FileHandler、轮转文件 RotatingFileHandler。
  • Formatter(格式器):决定日志长什么样,比如加上时间、级别、函数名。
  • Level(级别):给每条日志和每个 handler 设门槛,低于门槛的直接丢弃。

级别从低到高依次是 DEBUG、INFO、WARNING、ERROR、CRITICAL,对应数值大致是 10、20、30、40、50。 logger 只处理"级别 >= 阈值"的日志;日志要真正落地,还要通过 handler 的级别门槛,两道关卡都过才行。

相比 print,logging 的优势很实在:一行配置就能关掉所有调试信息,不必逐条删除 print;每条日志能自动带上时间、级别和来源模块,出问题时一眼看出是哪里、什么严重程度;还能同时写到多个地方并自动切分文件。这些能力在脚本阶段看似多余,一旦程序长期运行、需要多人协作排查,就会省下大量时间。

最小可用例子:

import logging

logging.basicConfig(level=logging.INFO)
logging.debug("这条不会显示")
logging.info("程序启动了")
logging.warning("磁盘空间偏低")

basicConfig 一次性配好根 logger 的级别、handler 和格式。默认格式是 级别:日志内容,加上 level=logging.INFO 后,DEBUG 被过滤掉。

二、实操步骤

下面分五步,把一个写满 print 的脚本迁移到 logging。保存为 demo_logging.py 运行。

第 1 步:把 print 换成级别化调用

对照替换:调试信息用 logger.debug,正常运行用 logger.info,需要提醒用 logger.warning,出错用 logger.error。先建好 logger:

import logging

logger = logging.getLogger(__name__)

def divide(a, b):
    logger.debug("准备计算 %s / %s", a, b)
    if b == 0:
        logger.error("除数不能为零")
        raise ValueError("除数不能为零")
    logger.info("计算完成")
    return a / b

注意用 %s 占位符而不是 f-string:只有日志真的要输出时才会做字符串拼接,f-string 则会提前算好,被过滤掉的日志也白算一遍。

第 2 步:用 basicConfig 配置全局行为

在程序入口(通常是 if __name__ == "__main__" 里)配置一次:

import logging

if __name__ == "__main__":
    logging.basicConfig(
        level=logging.INFO,
        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
    )
    logging.info("程序启动了")

%(asctime)s 是时间,%(levelname)s 是级别,%(name)s 是 logger 名字,也就是模块名。

第 3 步:同时输出到控制台和文件

basicConfig 不够灵活时,手动组装 handler:

import logging

logger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG)
logger.propagate = False

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

console = logging.StreamHandler()
console.setLevel(logging.INFO)
console.setFormatter(formatter)

file_handler = logging.FileHandler("app.log", encoding="utf-8")
file_handler.setLevel(logging.DEBUG)
file_handler.setFormatter(formatter)

logger.addHandler(console)
logger.addHandler(file_handler)

这样控制台只看到 INFO 及以上,文件里保留全部 DEBUG 信息。propagate = False 阻止日志继续向上冒泡到根 logger,避免同一条日志被打印两遍。

第 4 步:配置按大小轮转

日志文件长期写会越来越大,用 RotatingFileHandler 在超过阈值时切分:

import logging
from logging.handlers import RotatingFileHandler

logger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG)
formatter = logging.Formatter("%(asctime)s [%(levelname)s] %(name)s: %(message)s")

rotate = RotatingFileHandler(
    "app.log",
    maxBytes=1024 * 1024,   # 1 MB,按实际情况调整
    backupCount=3,
    encoding="utf-8",
)
rotate.setLevel(logging.DEBUG)
rotate.setFormatter(formatter)
logger.addHandler(rotate)

超过 maxBytes 后会生成 app.log.1、app.log.2 等备份,最多保留 backupCount 个。

第 5 步:配置按时间轮转

如果更希望每天一个文件,改用 TimedRotatingFileHandler:

import logging
from logging.handlers import TimedRotatingFileHandler

logger = logging.getLogger(__name__)
formatter = logging.Formatter("%(asctime)s [%(levelname)s] %(name)s: %(message)s")

daily = TimedRotatingFileHandler(
    "app.log",
    when="midnight",
    interval=1,
    backupCount=7,
    encoding="utf-8",
)
daily.setFormatter(formatter)
logger.addHandler(daily)

when="midnight" 表示每天零点切分,backupCount=7 表示保留最近 7 个备份。具体可选参数以官方文档为准。

三、关键细节

  1. basicConfig 只在第一次调用时生效:如果之前已经有人配置过 handler,再调它是无效的。调试时发现格式没变,通常是这个原因,清空 handler 后重配或只用一次。
  2. logger 和 handler 各有独立级别:两条门槛都要过。日志被过滤,先确认是哪一级挡住了。
  3. propagate 决定日志是否冒泡到父 logger:用了 basicConfig 又手动加 handler,常见后果就是日志重复输出两遍,设 propagate = False 可解决。
  4. 占位符用 %s 延迟求值:logger.debug("x=%s", x) 在级别不够时不会计算 x 的字符串形式,性能更好,也更安全。
  5. 轮转备份数量不是越大越好:备份会占用磁盘,按业务保留周期设置,并配合日志清理策略。
  6. 异常日志用 logger.exception:在 except 块里调用它会自动附带完整 traceback,比 logger.error(str(e)) 信息丰富得多。

四、常见错误

现象 原因 修正
设了 DEBUG 却看不到 debug 日志 只改了 logger 级别,handler 级别仍是 WARNING 把 handler 也 setLevel(logging.DEBUG)
同一条日志打印两遍 日志冒泡到根 logger,而根 logger 也有 handler 设 logger.propagate = False,或不要重复加 handler
改了 basicConfig 的格式但没生效 basicConfig 只在首次调用时生效 程序入口只调用一次,或先移除已有 handler
日志文件一直增长不切分 用的是普通 FileHandler,没有轮转 换成 RotatingFileHandler 或 TimedRotatingFileHandler
中文写进日志变成乱码 创建 handler 时没指定编码 FileHandler(..., encoding="utf-8")
异常日志看不到堆栈 用了 logger.error(str(e)) 只记了消息 在 except 里用 logger.exception("出错了")

五、排查方法

  1. 先确认日志级别:临时把 logger 和各 handler 都设成 DEBUG,看信息是否出现,再逐级调高定位门槛。
  2. 打印handler列表:运行 print(logger.handlers),确认实际挂了几个 handler、分别是什么类型。
  3. 检查重复:若输出重复,逐个设 propagate = False 或移除根 handler 再观察。
  4. 检查是否调用了 basicConfig:搜索代码中的 basicConfig,确保它在入口且只被调用一次。
  5. 验证落盘路径:用绝对路径写日志,确认目录存在且进程有写权限,避免相对路径指向意外位置。
  6. 轮转不生效时,先看文件大小是否真超过阈值、备份数是否已满,再换时间轮转对比。

六、注意事项

  • logging 是线程安全的,但多进程同时写同一个文件仍可能出问题,多进程场景应由主进程统一收集日志。
  • 不要在库模块里调用 basicConfig,那会替使用方做决定;库里只 getLogger(__name__),配置交给应用入口。
  • RotatingFileHandler 的 maxBytes 与 backupCount 取值应按实际磁盘和保留周期估算,本文示例仅示意,不代表推荐值。
  • 轮转策略与参数在不同 Python 版本中可能有细节差异,when 的可选值等请以官方文档为准。
  • 日志里不要记录密码、令牌等敏感信息,排查方便不能以泄露数据为代价。

免责声明:本文为个人学习与实操经验总结,仅代表个人观点,不构成任何技术或商业决策建议。不同系统环境与版本可能存在差异,实际操作请以官方文档为准并自行验证。