Python logging.Filter 如何给日志补充上下文：record 属性与多处理器链路

当同一套 Python 服务同时处理多个请求时，日志里如果只有消息文本，排查“这行日志属于哪个请求、哪个操作员”会很困难。logging.Filter 的合适用法，是在 LogRecord 进入处理器前补齐稳定上下文，再让不同 Handler 按自己的格式输出。

把上下文写入 record，再让 Formatter 读取；过滤器返回 True 表示记录继续流转，返回 False 才会丢弃这条记录。

先确定上下文应该在哪一层补齐

本例只补两个字段：trace_id 标识一次请求，operator 标识操作者。它们先由 ContextFilter.filter 写入 record，然后由挂在同一处理器上的 Formatter 读取。过滤器不负责拼接最终字符串，也不应该在每个业务调用点重复传入字段。

import logging

class ContextFilter(logging.Filter):
    def __init__(self, trace_id, operator):
        super().__init__()
        self.trace_id = trace_id
        self.operator = operator

    def filter(self, record):
        record.trace_id = self.trace_id
        record.operator = self.operator
        return True

logger = logging.getLogger("order")
handler = logging.StreamHandler()
handler.addFilter(ContextFilter("req-7f2a", "alice"))
handler.setFormatter(logging.Formatter(
    "%(levelname)s trace=%(trace_id)s operator=%(operator)s %(message)s"
))
logger.addHandler(handler)
logger.setLevel(logging.INFO)
logger.info("load order")

这段链路的可见结果是：logger.info 创建记录，ContextFilter.filter 写入两个属性，Formatter 再把属性放进输出。如果过滤器没有返回真值，记录不会继续交给这个处理器。

Formatter 字段必须和过滤器写入的属性成对出现

Formatter 中的 %(trace_id)s 和 %(operator)s 都要求记录拥有同名属性。只要有一条记录绕过了这个过滤器，就可能在格式化阶段出现缺少字段的问题。因此，过滤器的挂载位置比字段拼写更重要：如果多个来源都会进入同一处理器，应让它们都经过同一个补齐策略，或给 Formatter 提供明确的默认值。

不要把 record.message 当成自定义上下文字段。它由 Formatter 在格式化时根据消息和参数计算；自定义上下文应使用不会和标准 LogRecord 属性冲突的名称。

多个 Handler 时按输出边界决定过滤器挂载点

如果控制台和文件处理器要输出相同的上下文，可以把过滤器分别加到两个 Handler 上；如果过滤器挂在 Logger 上，则它的结果会影响后续处理器是否还能看到这条记录。更具体的分流规则也应放到对应处理器的过滤器中。

console = logging.StreamHandler()
file_handler = logging.FileHandler("orders.log", encoding="utf-8")

context = ContextFilter("req-7f2a", "alice")
console.addFilter(context)
file_handler.addFilter(context)

console.setFormatter(logging.Formatter("console %(trace_id)s %(message)s"))
file_handler.setFormatter(logging.Formatter("file %(trace_id)s %(operator)s %(message)s"))
logger.addHandler(console)
logger.addHandler(file_handler)

这样配置后，同一个 LogRecord 会沿着两个处理器分别执行过滤器和格式化器。检查结果时应看到控制台和 orders.log 都有 trace_id，文件输出还包含 operator。

缺失上下文时选择默认值还是丢弃记录

后台任务可能没有操作者，但通常仍值得保留日志。可以在过滤器里写入固定的 operator 默认值；只有明确不属于目标输出的记录，才返回 False。判断标准是“这条记录是否应该出现在这个 Handler”，不是“上下文字段是否完整”。

class OptionalContextFilter(logging.Filter):
    def __init__(self, trace_id, operator="system"):
        super().__init__()
        self.trace_id = trace_id
        self.operator = operator

    def filter(self, record):
        record.trace_id = getattr(record, "trace_id", self.trace_id)
        record.operator = getattr(record, "operator", self.operator)
        return True

用一条最小检查清单验证配置

1. 确认 ContextFilter.filter 给 record 写入了 Formatter 使用的每个字段。
2. 确认需要上下文的每个 Handler 都挂载了过滤器。
3. 分别触发控制台与文件输出，检查 trace_id 是否一致、operator 是否按预期出现。
4. 用没有操作者的后台任务验证默认值，不要用缺字段异常替代业务日志。

以上配置和行为可在 Python 官方 logging API 文档及Logging Cookbook中交叉核对。

相关问答：Filter 配置还容易错在哪里

问：过滤器应该挂在 Logger 还是 Handler？ 如果所有输出都需要同一上下文，可以统一挂在 Logger；如果不同输出需要不同字段或分流，挂在各自 Handler 更容易控制边界。

问：为什么 Formatter 报缺少字段？ 通常是某条 LogRecord 没有经过写入该属性的 Filter，或者 Formatter 中的属性名与过滤器写入的名称不一致。