Python logging Formatter 统一结构化字段输出

我第一次把 Python 服务的日志交给检索系统时，真正麻烦的不是把日志改成 JSON，而是不同模块输出的字段不稳定：有请求日志带 request_id，有后台任务没有；一旦 Formatter 直接读取缺失字段，整条日志就可能在格式化阶段报错。比较稳妥的做法是把字段流转拆开：extra 负责把业务上下文放进 LogRecord，Formatter 负责统一布局，defaults 负责兜底，最后由 Handler 送到文件或标准输出。

官方资料：https://docs.python.org/3/library/logging.html

我先把字段放进 LogRecord，再交给 Formatter

Python 标准库的日志对象可以看成一条待加工记录。调用 logger 时，消息和参数形成基础内容，extra 字典则会把自定义属性写入这条 LogRecord。Formatter 读取记录属性，决定时间、级别、 logger 名称和业务字段怎样组合成最终字符串。

这一区分很重要：extra 不是 Formatter 的格式模板，style 也不是把日志调用改成 str.format()。它只决定 fmt 模板采用百分号、花括号或模板字符串哪一种写法；日志调用本身仍按 logging 的消息参数规则处理。

defaults 解决的是缺字段，不是业务字段设计

如果格式模板直接写了 %(request_id)s，但某条日志没有传同名属性，Formatter 在合并字段时就会遇到缺失问题。我的经验是先列出一份稳定字段契约：请求服务统一有 request_id，没有请求上下文的定时任务就使用 "-"；用户字段同理。这样检索系统可以依赖固定键，不必为每条日志猜字段是否存在。

Python 的 logging.Formatter 支持 defaults 为自定义字段提供默认值。它适合解决“字段偶尔没有”的问题，但不应该掩盖业务代码忘记传递关键上下文。像租户标识、审计主体这类强约束字段，我会在上游显式构造，而不是静默填充。

用一个 Formatter 统一标准字段和 JSON 输出

下面的 Formatter 保留标准字段，同时把 request_id、user_id 和异常文本放进稳定的 JSON 对象。代码里的 format() 只负责把一条 LogRecord 变成字符串，Handler 仍然负责选择输出位置。

import json
import logging


class StructuredFormatter(logging.Formatter):
    def __init__(self):
        # defaults 给没有请求上下文的后台任务提供可检索的占位值。
        super().__init__(defaults={"request_id": "-", "user_id": "-"})

    def format(self, record: logging.LogRecord) -> str:
        # getMessage() 保留 logging 原本的消息参数合并行为。
        payload = {
            "time": self.formatTime(record, "%Y-%m-%dT%H:%M:%S%z"),
            "level": record.levelname,
            "logger": record.name,
            "message": record.getMessage(),
            "request_id": getattr(record, "request_id", "-"),
            "user_id": getattr(record, "user_id", "-"),
        }
        if record.exc_info:
            # 将异常栈转成字段，避免把多行文本混进固定键之外。
            payload["exception"] = self.formatException(record.exc_info)
        # ensure_ascii=False 让中文消息保持可读，便于人工排查。
        return json.dumps(payload, ensure_ascii=False)


logger = logging.getLogger("orders")
logger.setLevel(logging.INFO)
handler = logging.StreamHandler()
# Handler 只选择出口，字段布局集中交给同一个 Formatter。
handler.setFormatter(StructuredFormatter())
logger.addHandler(handler)

logger.info("订单已创建", extra={"request_id": "req-1001", "user_id": "u-9"})
logger.info("定时清理完成")

这里第二条日志没有传 extra，但 Formatter 仍然输出相同的键集合。需要注意的是，示例使用 getattr() 做了显式兜底；如果项目直接用字符串模板读取自定义字段，可以把 defaults 与上游字段规范一起保留，避免不同 Handler 各自发明默认值。

我会按字段契约检查这几个边界

第一，业务字段名称不要与 LogRecord 的标准属性冲突，尤其不要用 message、name、levelname 这类已有名称覆盖内部信息。第二，输出给机器解析的字段应保持标量或明确的嵌套结构，避免同一个键一会儿是字符串、一会儿是对象。第三，异常日志要保留 traceback，但不要把密码、令牌或完整请求体塞进异常字段。

我通常会用一组包含“有上下文、无上下文、带异常”三种情况的固定样例做人工复查：字段集合是否一致，时间格式是否统一，中文是否可读，异常是否仍能定位。确认这些边界后，再把 Formatter 复用到文件 Handler、标准输出 Handler 或队列适配器上，维护成本会比在每个调用点拼接字符串低很多。

常见问题

Formatter 的 style 设置成花括号后，日志调用也要改成 str.format() 吗？

不用。style 只影响 Formatter 的 fmt 模板，例如输出模板中的 {message}；它不改变 logger 方法接收消息和参数的方式。

所有业务字段都应该放进 extra 吗？

适合随单条日志变化的上下文可以放进 extra。跨整个请求或线程都需要的字段，更适合通过统一的过滤器、记录工厂或上游上下文注入，避免每个调用点手写一遍。

defaults 能不能替代字段校验？

不能。它解决的是可选字段缺失时的输出稳定性；审计主体、租户等关键字段仍应在业务边界显式校验，不能用占位符掩盖数据缺口。