Python logging.handlers 如何按大小滚动日志：备份数量、编码设置与多进程边界

线上服务的日志目录突然只剩下一个不断变大的 service.log，配置里明明写了 RotatingFileHandler。这类问题通常不是“滚动失效”，而是阈值、备份数、文件编码和进程模型没有一起核对。下面用一个可复现的小场景，把每个边界拆开看。

先复现日志文件没有按预期滚动

先把阈值压到 1 KiB，便于在本地快速观察。生产环境不要照搬这个数值，阈值应按单日写入量、磁盘余量和采集端延迟一起估算。

import logging
from logging.handlers import RotatingFileHandler

handler = RotatingFileHandler(
    "service.log",
    maxBytes=1024,
    backupCount=3,
    encoding="utf-8",
)
handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
logger = logging.getLogger("demo")
logger.setLevel(logging.INFO)
logger.addHandler(handler)

for index in range(300):
    logger.info("request=%s payload=%s", index, "x" * 40)

handler.close()

运行后，目录里应看到 service.log、service.log.1、service.log.2 和 service.log.3。当前文件可能还没有达到 1 KiB，旧文件则是最近几次切换保存下来的内容。

逐项核对四个最容易误解的参数

maxBytes 决定什么时候触发

maxBytes=0 表示不按大小滚动，即使 backupCount 写成了 5，也不会自动切换。阈值判断发生在写入前后相邻的处理流程中，所以单条超长日志可能让文件短暂超过阈值，这不是精确的硬上限。

backupCount 决定保留多少个旧文件

设置为 3 后，滚动文件的编号范围是 .1 到 .3。下一次切换时，最旧的 .3 会被淘汰，.2 变成 .3，依次类推，原来的当前文件成为 .1。如果希望目录里总共不超过四个日志文件，还要把当前文件算进去。

encoding 和 delay 解决的是打开方式，不是滚动策略

中文日志建议明确写 encoding="utf-8"，避免运行环境默认编码不同造成读取乱码。delay=True 会推迟到第一次真正写入时再打开文件，适合初始化阶段可能不产生日志的服务；它不会改变备份数量。

用检查清单定位“配置看似正确却不滚动”

1. 确认实际挂载的是 RotatingFileHandler，没有被另一套 FileHandler 或重复 handler 覆盖。
2. 打印最终生效的 maxBytes 和 backupCount，不要只看配置文件模板。
3. 确认进程对日志目录有创建、改名和删除权限；滚动过程需要这些文件操作。
4. 检查采集器是否只采集固定文件名。滚动后要让采集器识别 .1、.2 等历史文件，或配置正确的 glob。
5. 让测试日志超过阈值，再检查修改时间和文件编号，不要用空启动来判断。

这里别急着增大 backupCount。如果采集器只跟踪 service.log，备份越多，越可能把未采走的历史内容留在本地。

多进程为什么是另一条边界

RotatingFileHandler 适合单个进程内的日志滚动。多个进程同时打开同一个文件时，谁先判断大小、谁执行改名、另一个进程手里的文件描述符指向哪里，都可能互相打架，结果包括覆盖备份、遗漏记录和编号顺序异常。

更稳妥的做法有两类：让每个进程写独立文件，再由采集端按进程名汇总；或者让进程把日志交给一个集中写入的服务/线程，由唯一写入者负责滚动。不要把“加大备份数”当成多进程安全方案。

一份适合单进程服务的收口配置

handler = RotatingFileHandler(
    filename="/var/log/my-service/service.log",
    maxBytes=50 * 1024 * 1024,
    backupCount=7,
    encoding="utf-8",
    delay=True,
)

这段配置表达的是“单进程、每个文件约 50 MiB、保留 7 个旧文件、按 UTF-8 打开、无日志时不提前创建”。真正上线前还要验收目录权限、磁盘告警、采集规则和进程模型。

相关问题

backupCount 设置为 0 会怎样？

不会保留旧文件，通常也就失去了按大小滚动后留存历史日志的意义。需要保留排障证据时，应设置明确的备份数并配套磁盘预算。

按日期切换应该换哪个 handler？

按日期切换应看 TimedRotatingFileHandler。它的间隔和保留策略与按大小的 maxBytes 不同，不建议混用两个 handler 共同管理同一路径。

为什么文件大小会超过 maxBytes？

阈值是在写入流程中判断的，单条日志本身可能较大；此外，其他进程或外部程序追加同一个文件也会让结果偏离。先确认是否存在共享写入，再判断参数是否失效。

总结

排查 Python 日志滚动时，先确认 handler 类型和 maxBytes，再按当前文件、编号备份、采集规则和进程模型逐项验收。单进程场景用 backupCount 控制留存；多进程场景先解决“谁是唯一写入者”，否则参数调得再漂亮也可能留下缺口。