用 Python logging 实现优雅的结构化日志输出

52JinY 助手

这两年在几个项目里折腾 Python 日志，越用越觉得“结构化输出”是门槛最低却收益最大的改造。传统的日志一条条字符串，查问题像在日志海里捞针；一旦把日志变成有字段的结构，检索、聚合、告警、可视化全都顺滑起来。尤其是接 ELK、OpenSearch、Datadog 这种平台，结构化就是入场券。

先说“结构化”的核心：别把信息塞进一句话里让人去 parse，而是把关键信息变成字段。最常见的载体是 JSON，因为生态最完善。Python 的 logging 原生是面向字符串的，但并不妨碍我们做两层改造：一是把上下文变成 LogRecord 的属性；二是用自定义 Formatter 把 LogRecord 序列化成 JSON。社区里有成熟方案，比如 structlog（https://www.structlog.org/）和 python-json-logger（https://pypi.org/project/python-json-logger/）。我个人更偏向“轻度依赖”的做法：标准库 logging + 一个 JSONFormatter 足够覆盖 80% 需求。

怎么落地？我总结了三条实践路径。第一条是“就地结构化”，继续用 logging.getLogger()，但约定所有业务日志都通过 logger.info("msg", extra={...}) 填字段，同时在 Formatter 里读取 record.__dict__ 序列化。好处是改造成本低，坏处是容易漏字段、字段名不统一。第二条是“上下文绑定”，给每个请求或任务生成一个带 request_id、user_id 的 LoggerAdapter 或者使用 contextvars，把这些公共字段自动注入；代码里只写 logger.info("order created", extra={"order_id": ...})，不会每次都手填 request_id。第三条是“事件驱动”，也就是 structlog 的思路：logger.info("order_created", order_id=..., amount=...)，由处理链把事件名、时间、级别、上下文拼成最终 JSON。这条曲线稍陡，但一致性最好。

字段设计也有讲究。我建议把四个层面的信息分开：平台字段（timestamp、level、logger、process、thread）、请求上下文（request_id、trace_id、span_id、user_id、ip）、业务维度（order_id、tenant、region）、事件数据（amount、status 等）。事件名用动词过去式或名词短语，像 order_created、payment_failed，便于在检索里做 terms 聚合。时间戳统一 ISO8601 且带时区，比如 2026-06-29T08:12:03.123Z。数值字段保持数值类型，别转成字符串，这关系到后续仪表盘的可视化。

还有两个冷门但关键的细节。其一是异常结构化：不要只打印 traceback 字符串。建议捕获异常后，字段化异常类型、消息、栈帧（只保留必要帧，避免超长日志），再把栈作为单独字段 stack，让观测平台能高亮和折叠。其二是日志体积控制：结构化容易“滥字段”，要设白名单或用正则清洗；对大对象（比如响应体、SQL 结果）要么做采样，要么只记录摘要与哈希，避免把存储当缓存用。

很多人担心性能。我的经验是：JSON 序列化的开销在 I/O 面前通常可以忽略，但要注意两点优化。第一，使用异步/队列 Handler，把格式化好的 JSON 交给后台线程写文件或推送（例如 QueueHandler + QueueListener），避免阻塞主线程。第二，避免在 debug/info 级别构造昂贵对象，利用 lazy 格式化或先判断 logger.isEnabledFor(level) 再计算字段。

最后谈落地顺序。别一上来全局重构，选一条典型链路（比如下单），定义事件名和字段，接入 JSON 输出到本地文件，然后用 Filebeat/Fluent Bit ship 到你的日志平台。把一条链路跑通后，沉淀字段规范与代码模板，再逐步推广。等有了基础设施，再考虑接入分布式追踪，把 trace_id/span_id 串起来，日志、指标、追踪三位一体，问题定位的效率会有质的提升。

结构化日志不是炫技，而是把“人肉解析”交给机器。做对了，你的运维与排错从“看天吃饭”变成“可计算的事实”。在混沌里加一点结构，收益远超预期。