Python logging.Filter 返回 False 时怎样阻止单条记录

logging.Filter.filter(record) 返回 False，会拒绝该过滤器所处位置上的这条记录。挂在 Handler 上，只阻止这个 Handler 输出；挂在产生记录的 Logger 上，则在记录交给处理器之前拒绝它。要屏蔽一条日志，先确定希望影响一个输出目的地，还是该源 Logger 的全部输出。

官方地址：https://docs.python.org/3.14/library/logging.html

前置条件：把级别、过滤器和传播分开

日志级别适合按严重程度筛选，Filter 适合根据记录属性做更细的判断。例如 INFO 级别里既有希望显示的提示，也有只需归档的内部记录，统一提高级别会一起丢掉它们。可用 extra 给某一条记录附加标志，再在目标处理器上判断。

这个小实验设置一个源 Logger、两个 StreamHandler 和两个内存缓冲区。命名为 screen 的目的地只接收 INFO 及以上，并拒绝带屏蔽标记的记录；archive 接收 DEBUG 及以上，不加这条过滤。它们不是实际终端或文件，只是为了清楚地比较去向。

初始化：隔离示例配置，避免 root 的额外输出

通过唯一 Logger 名称创建独立配置，并设置 propagate=False，防止当前记录又被祖先处理器输出一次。示例没有修改 root，也没有清空已有处理器。实际应用应在启动阶段统一配置日志，而不是每次请求都创建新 Logger。

编写代码：用记录字段决定单个 Handler 是否接受

import io
import logging
import uuid

class SkipMarked(logging.Filter):
    def filter(self, record):
        # 缺省不屏蔽；只拒绝显式标记的单条记录。
        return not getattr(record, "skip_screen", False)

def main():
    screen = io.StringIO()
    archive = io.StringIO()
    # 为独立演示选用唯一名称，不清空其他应用的处理器。
    logger = logging.getLogger("filter_lab." + uuid.uuid4().hex)
    logger.setLevel(logging.DEBUG)
    logger.propagate = False

    screen_handler = logging.StreamHandler(screen)
    archive_handler = logging.StreamHandler(archive)
    screen_handler.setLevel(logging.INFO)
    archive_handler.setLevel(logging.DEBUG)
    screen_handler.addFilter(SkipMarked())
    formatter = logging.Formatter("%(levelname)s %(message)s")

    handlers = (screen_handler, archive_handler)
    for handler in handlers:
        handler.setFormatter(formatter)
        logger.addHandler(handler)
    try:
        logger.info("visible")
        logger.info("marked", extra={"skip_screen": True})
        logger.debug("detail")
        # 内存缓冲区代替真实终端和文件，便于比较两个目的地。
        print("screen:", screen.getvalue().splitlines())
        print("archive:", archive.getvalue().splitlines())
    finally:
        # 只移除并关闭本例创建的处理器。
        for handler in handlers:
            logger.removeHandler(handler)
            handler.close()
        screen.close()
        archive.close()

if __name__ == "__main__":
    main()

SkipMarked 中返回的是显式布尔值。getattr 的默认值让没有 skip_screen 属性的普通记录通过，避免把“缺少字段”误当成屏蔽。只有 marked 那次调用带上 extra，其他记录不会被永久关闭；过滤结果作用于当前记录，不会把 Logger 或 Handler 设成 disabled。

不要在 filter 里只写 print 然后忘记 return。Python 函数默认返回 None，在这里属于假值，会拒绝本来准备放行的记录。也不要用修改日志级别代替返回 False，因为修改 LogRecord 可能影响其他处理器看到的内容。

运行检查说明：一条记录可以在两个目的地得到不同结果

将代码保存成独立脚本后可按下面的预期理解输出。这里是代码规则推导，没有声称已经执行，也没有把图示当作运行截图。

screen: ['INFO visible']
archive: ['INFO visible', 'INFO marked', 'DEBUG detail']

最后一条与 Filter 拒绝不同：它在正常 Logger 分发路径上就没达到 screen_handler 的级别门槛。因此排查“过滤器为什么没有被调用”时，还应先看源 Logger 的有效级别和对应 Handler 的级别，不能只在 filter 方法里加更多判断。

扩展实验：移动挂载位置会改变影响范围

如果需求是“这条记录在该源 Logger 的全部目的地都不要出现”，可以把 SkipMarked 挂到源 logger，而不是 screen_handler。使用同一标志时，marked 会在交给两个处理器前被拒绝。这是配置位置的变化，不是 Handler 过滤器失效。

另一个容易误判的场景是层级传播：把过滤器挂在 app Logger 上，然后通过 app.child 记录，并不意味着 app 的 Logger Filter 会重新筛选这条子记录。传播直接交给祖先 Handler；想让祖先的某个输出目的地统一筛选，应把规则挂到那个 Handler 上，或者明确配置每个源 Logger。

propagate=False 也不是“拒绝当前记录”的同义写法：它阻止向祖先继续传播，当前 Logger 自己的 Handler 仍能处理。若同一条记录打印两次，还应检查源与祖先是否都挂了输出处理器，不要仅靠给其中一个目的地加过滤器掩盖重复配置。

清理：只移除自己持有的处理器

示例 finally 里先 removeHandler，再 close，最后关闭内存流。清理范围限定为本例创建的资源。服务或库代码不应随手清空 root.handlers，否则可能移除宿主程序的日志输出。独立演示使用唯一 Logger 名称是隔离方式，长期运行的应用则应复用稳定名称，避免不断扩大 Logger 注册表。

如果以后增加更多 Filter，同一位置上的规则会依次判断，其中一个返回假值就停止处理当前记录。多个 Filter 默认不是“任意一个同意就通过”。需要 OR 规则时，应在一个明确的谓词里组合条件，保持字段缺省值与返回语义一致。

相关问题

返回 False 会撤回已经输出的日志吗

不会。它只能拒绝尚未经过该位置的输出；另一个 Handler 若已经写出，当前 Filter 无法删除那份内容。应在所需目的地输出前配置规则。

Python 3.12 返回 LogRecord 的能力会改变 False 的含义吗

不会。3.12 起过滤器可以返回替换的 LogRecord；False 仍表示拒绝。只想屏蔽单条记录时，用明确的布尔返回即可，不需要复制记录。

为什么同一个筛选条件在文件与控制台表现不同

先比较两个 Handler 的级别和 Filter 列表，再看是否发生祖先传播。每个目的地都可以有独立规则，不能因为一个 Handler 拒绝就推断所有输出都会停止。

参考资料

• Python logging：Filter、级别与传播
• Logging HOWTO：日志处理结构
• Logging Cookbook：多处理器与配置示例