Python logging Filter 修改 LogRecord 如何隔离 handler

同一个 Python logger 同时写控制台和审计文件时，最容易踩到的坑是：Filter 直接修改共享的 LogRecord，后面的 handler 也看到了不该出现的字段。更稳妥的做法是把 Filter 挂在目标 handler 上，在 Python 3.12 及以上用 copy.copy() 复制记录，只修改副本并返回它。

要隔离 handler 字段，关键不是再建一个 logger，而是把 Filter 放在目标 Handler 上，并返回新的 LogRecord；Logger 级 Filter 仍然会影响后续所有 handler。

先分清 logger、handler 与 Filter 的作用范围

Logger 生成 LogRecord，然后把记录交给自身及祖先 logger 上的 handler；Handler 决定写到哪里，Formatter 决定长什么样。Filter 可以挂在 Logger 或 Handler 上，但两者不是同一个范围。

如果把过滤器挂在 logger 上，它通常会在记录送往 handler 前参与判断，修改也会沿着后续输出继续传播。把过滤器挂在审计 handler 上，则只让审计输出获得额外字段。注意，handler 级 Filter 仍然可以拒绝记录；“局部”说的是字段修改的目标，不是绕过级别判断。

为什么直接修改 LogRecord 会污染另一个 handler

下面这个写法看似简单，却把审计字段写回了共享对象：

class AuditFilter(logging.Filter):
    def filter(self, record):
        # 直接改原记录，后续 handler 也可能读到 audit_scope。
        record.audit_scope = "finance"
        return True

当控制台 handler 的格式化字符串也使用 %(audit_scope)s 时，字段会意外出现在控制台；如果控制台 Formatter 没有这个占位符，问题可能暂时不显眼，但共享可变对象的风险依旧存在。

用返回新 LogRecord 实现 handler 级字段隔离

Python 3.12 起，Filter 可以返回一个新的 LogRecord。下面让审计 handler 读取副本，控制台 handler 继续读取原始记录：

import copy
import logging

class JsonFieldFilter(logging.Filter):
    def filter(self, record):
        # 复制共享记录，只给审计输出增加上下文。
        isolated = copy.copy(record)
        isolated.audit_scope = "finance"
        # 把已格式化消息固定下来，避免复制后仍依赖原 args。
        isolated.msg = record.getMessage()
        isolated.args = ()
        return isolated

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

console = logging.StreamHandler()
console.setFormatter(logging.Formatter("控制台 %(levelname)s %(message)s"))

audit = logging.FileHandler("audit.log", encoding="utf-8")
audit.addFilter(JsonFieldFilter())
audit.setFormatter(logging.Formatter("审计 %(audit_scope)s %(message)s"))

logger.addHandler(console)
logger.addHandler(audit)
logger.info("invoice paid")  # 审计文件有 finance，控制台没有该字段。

这里的隔离点有三个：Filter 只附加到 audit；副本由 copy.copy(record) 创建；审计 Formatter 使用的字段只写入副本。生产代码还应避免重复添加 handler，否则同一条消息可能被输出多次。

版本边界与排查清单

如果运行环境低于 Python 3.12，Filter 返回新 LogRecord 不会按本文方式替换记录。此时可把需要的上下文放在调用处，通过 LoggerAdapter 或独立 logger 传递；若必须在 Filter 中添加字段，就要明确它是原地修改，并检查所有 handler 的 Formatter 是否能接受该字段。

遇到“字段没有隔离”时，依次检查：Filter 是加在 Logger 还是目标 Handler；目标 handler 是否真的被调用；Formatter 是否引用了新增字段；应用是否重复注册 handler；当前 Python 版本是否支持返回 LogRecord。

相关问题

Filter 返回 False 会发生什么？

当前挂载点的记录会被丢弃；如果是 handler 级 Filter，只影响这个 handler，不代表其他 handler 一定收不到。

为什么不直接给所有 LogRecord 加字段？

只有所有输出都需要该字段时才适合统一注入。审计、脱敏和结构化字段通常属于单个输出边界，复制后修改更安全。

Python 3.11 能否照搬示例？

不能依赖返回副本的语义。应改用 LoggerAdapter、独立 logger，或接受 Filter 原地修改并为所有 Formatter 补齐字段。

判断标准很简单：全局规则放 Logger，某一种输出专属的字段放 Handler；需要修改时优先返回副本，并把 Python 版本边界写进项目运行要求。