Python logging Filter 如何替换 LogRecord：按 Handler 改写字段与并发边界

同一条 Python 日志同时写入控制台和文件时，最容易踩到一个隐蔽问题：为了给文件日志补充字段，Filter 直接改了原来的 LogRecord，结果控制台也被迫带上了不该出现的内容。更麻烦的是，多个 Handler 共用同一条记录，改动发生在哪里并不直观。

Python 3.12 之后，挂在 Handler 上的过滤器可以返回一个新的 LogRecord，让改写只影响当前 Handler。旧版本仍然只能在原记录上修改或放弃这条记录，因此兼容写法要提前想清楚。

要按不同输出目标改写日志字段，把过滤器挂在具体 Handler 上，并在 Python 3.12+ 返回新的 LogRecord；不要在共享记录上原地修改敏感字段。

先看一个会污染控制台的 Filter

假设文件日志需要记录完整的 request_id，控制台只希望保留简短消息。下面的过滤器直接改写记录字段，看起来很顺手：

import logging

class AddRequestId(logging.Filter):
    def filter(self, record):
        record.request_id = "req-42"
        return True

logger = logging.getLogger("checkout")
console = logging.StreamHandler()
file_handler = logging.FileHandler("service.log", encoding="utf-8")
file_handler.addFilter(AddRequestId())
logger.addHandler(console)
logger.addHandler(file_handler)
logger.warning("payment retry")

这里的关键不是 True，而是修改发生在共享的 record 上。Handler 的执行顺序、Formatter 是否读取该字段，都会影响最后看到的结果。把过滤器换到控制台 Handler 上，仍然不能自动得到“只影响控制台”的隔离效果。

Python 3.12+ 的变化：Filter 可以返回新记录

新的语义允许 filter 返回一个 LogRecord。返回 False 仍表示丢弃记录，返回真值表示继续处理；只有返回新记录时，当前 Handler 才会用它替换原记录。

import logging

class FileRecordFilter(logging.Filter):
    def filter(self, record):
        replacement = logging.makeLogRecord(record.__dict__.copy())
        replacement.request_id = "req-42"
        replacement.channel = "file"
        return replacement

console = logging.StreamHandler()
console.setFormatter(logging.Formatter("console: %(message)s"))

file_handler = logging.FileHandler("service.log", encoding="utf-8")
file_handler.setFormatter(
    logging.Formatter("%(levelname)s %(request_id)s %(message)s")
)
file_handler.addFilter(FileRecordFilter())

过滤器放在 file_handler 上，因此文件 Formatter 读取替换记录里的 request_id，控制台 Handler 仍处理原始记录。这个做法的收益是字段改写的作用域跟着 Handler 走，审计字段、脱敏字段和输出渠道可以分开管理。

为什么要复制 LogRecord，而不是拼一个新对象

LogRecord 除了消息文本，还有名称、级别、创建时间、异常信息和调用位置等运行时字段。直接调用构造函数容易漏掉 pathname、lineno 或 exc_info。用 logging.makeLogRecord(record.__dict__.copy()) 可以保留当前记录的字段，再只修改本 Handler 需要的属性。

这不是深拷贝。自定义字段如果指向可变对象，复制后的记录仍可能共享这份数据。日志上下文尽量用字符串、数字这类不可变值存储；如果字段本身是字典，要先生成脱敏后的新字典，再放到 replacement 里。

兼容 Python 3.11：先区分目标，再决定写法

Python 3.11 及更早版本不会把过滤器返回的新 LogRecord 当作替换结果。需要兼容旧运行时的场景，可以选下面三种方案：

• 只做放行或丢弃：过滤器继续返回布尔值，不改动原有记录。
• 必须改字段：接受原地修改会影响后续 Handler 的逻辑，同时保证所有 Formatter 都能识别这些新增字段。
• 必须隔离不同输出：写一个自定义 Handler，在内部复制记录后再交给 Formatter，或者把分流逻辑放到独立 Logger 上。

不要只在代码里标注“支持 Python 3.12”，还要在 CI 里跑一条行为测试：分别捕获控制台和文件 Handler 的输出，断言新字段只出现在预期的输出目标里。判断版本时优先做能力测试，不要只依赖版本字符串比较。

并发和异常场景怎么验收

过滤器会在日志处理路径上运行。它不应修改全局变量来保存“当前请求”，也不应因为一次脱敏失败而静默吞掉整条错误日志。请求标识可以从 contextvars.ContextVar 读取，复制记录时把当前值写入 replacement。

import contextvars
import logging

request_id = contextvars.ContextVar("request_id", default="-")

class RequestFilter(logging.Filter):
    def filter(self, record):
        copy = logging.makeLogRecord(record.__dict__.copy())
        copy.request_id = request_id.get()
        return copy

def log_one(logger, value):
    token = request_id.set(value)
    try:
        logger.info("worker finished")
    finally:
        request_id.reset(token)

验收的时候至少覆盖三种场景：同一条日志经过两个不同 Handler；两个并发任务使用不同的 request_id；Formatter 读取一个不存在的字段。第三种情况要在测试阶段就暴露出来，不要等到生产环境格式化日志的时候才报错。

常见问题

Filter 返回 LogRecord 后，Logger 的其他 Handler 也会收到新记录吗？

不会。替换语义只发生在当前 Handler 的过滤阶段，其他 Handler 仍然可以处理原始记录。

Filter 返回 True 能不能同时替换记录？

不能。返回 True 只代表继续往下走处理流程；要完成记录替换，必须返回一个全新的 LogRecord 对象。

Python 3.11 项目能直接使用这种写法吗？

不能把这个特性当成隔离替换来依赖。旧版本运行时还是要用布尔过滤、原地修改加统一 Formatter，或者自行实现 Handler 分流的逻辑。

为什么测试里 request_id 偶尔串了？

这类问题的常见原因是用全局变量保存当前请求，或者把可变上下文对象浅复制之后又继续修改。优先用 ContextVar 存储上下文，同时保证 replacement 里的所有字段都是不可变类型。

落地前的检查清单

先确认运行时版本，再确认过滤器是挂在 Logger 上还是具体 Handler 上。只要需求是“不同输出通道展示不同字段”，就优先选 Handler 级过滤器、复制 LogRecord 返回 replacement 的方案，同时用双 Handler 测试验证原记录没有被污染。