一、基础知识
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 个备份。具体可选参数以官方文档为准。
三、关键细节
basicConfig只在第一次调用时生效:如果之前已经有人配置过 handler,再调它是无效的。调试时发现格式没变,通常是这个原因,清空 handler 后重配或只用一次。- logger 和 handler 各有独立级别:两条门槛都要过。日志被过滤,先确认是哪一级挡住了。
propagate决定日志是否冒泡到父 logger:用了basicConfig又手动加 handler,常见后果就是日志重复输出两遍,设propagate = False可解决。- 占位符用
%s延迟求值:logger.debug("x=%s", x)在级别不够时不会计算x的字符串形式,性能更好,也更安全。 - 轮转备份数量不是越大越好:备份会占用磁盘,按业务保留周期设置,并配合日志清理策略。
- 异常日志用
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("出错了") |
五、排查方法
- 先确认日志级别:临时把 logger 和各 handler 都设成
DEBUG,看信息是否出现,再逐级调高定位门槛。 - 打印handler列表:运行
print(logger.handlers),确认实际挂了几个 handler、分别是什么类型。 - 检查重复:若输出重复,逐个设
propagate = False或移除根 handler 再观察。 - 检查是否调用了
basicConfig:搜索代码中的basicConfig,确保它在入口且只被调用一次。 - 验证落盘路径:用绝对路径写日志,确认目录存在且进程有写权限,避免相对路径指向意外位置。
- 轮转不生效时,先看文件大小是否真超过阈值、备份数是否已满,再换时间轮转对比。
六、注意事项
- logging 是线程安全的,但多进程同时写同一个文件仍可能出问题,多进程场景应由主进程统一收集日志。
- 不要在库模块里调用
basicConfig,那会替使用方做决定;库里只getLogger(__name__),配置交给应用入口。 RotatingFileHandler的maxBytes与backupCount取值应按实际磁盘和保留周期估算,本文示例仅示意,不代表推荐值。- 轮转策略与参数在不同 Python 版本中可能有细节差异,
when的可选值等请以官方文档为准。 - 日志里不要记录密码、令牌等敏感信息,排查方便不能以泄露数据为代价。
免责声明:本文为个人学习与实操经验总结,仅代表个人观点,不构成任何技术或商业决策建议。不同系统环境与版本可能存在差异,实际操作请以官方文档为准并自行验证。

评论
还没有评论,来说两句吧。