17370845950

默认 logging 不能直接输出 JSON，因其 Formatter 将日志拼为字符串且字段不可控；需自定义 Formatter 子类重写 format()，过滤不可序列化字段、处理异常堆栈、用 json.dumps() 输出合法 JSON，并通过 LoggerAdapter 或 Filter 注入 trace_id 等上下文字段。

为什么默认的 logging 不能直接输出 JSON

Python 标准库的 logging 默认使用 Formatter，它把日志拼成字符串，字段顺序、类型、嵌套结构都不可控。想让日志变成 JSON，关键不是“加个参数”，而是替换掉格式化逻辑——必须自定义一个继承自 logging.Formatter 的类，重写 format() 方法，让它返回合法 JSON 字符串。

如何写一个可靠的 JSON Formatter

核心是：在 format() 中提取 record.__dict__，剔除不可序列化的字段（比如 exc_info、stack_info），再把异常和堆栈转成字符串后塞进新字典，最后用 json.dumps() 输出。常见错误是直接 dump 整个 record.__dict__，结果遇到 threading.Lock 或函数对象就报 TypeError: Object of type Lock is not JSON serializable。

• 必须过滤掉 exc_info、stack_info、msg（原始格式化字符串）、args（未格式化的元组）这些非基础类型字段
• 用 self.formatException(record) 和 self.formatStack(record) 获取可序列化的异常/堆栈字符串
• 推荐设置 ensure_ascii=False 和 separators=(',', ':') 减少体积
• 时间字段建议用 record.created 或 datetime.fromtimestamp(record.created)，别依赖 record.asctime（那是字符串，且格式不统一）

如何让 JSON 日志包含 trace_id 或 request_id

结构化日志的价值在于关联请求链路，但 logging.Record 默认不带上下文字段。不能靠全局变量或线程局部存储硬塞——并发下会错乱。正确做法是用 LoggerAdapter 或 Filter 动态注入字段。

• 用 LoggerAdapter 最简单：初始化时传入 extra={'trace_id': 'xxx'}，之后所有 logger.info() 调用都会自动带上该字段
• 如果需要动态值（比如从 Flask 请求中取 request.headers.get('X-Request-ID')），必须写自定义 Filter，在 filter(record) 里设置 record.trace_id = get_current_trace_id()
• 注意：Filter 注入的字段名必须在 JSON Formatter 的 format() 中显式读取，否则不会出现在输出里

FileHandler + JSON Formatter 的实际坑点

本地开发时用 FileHandler 配 JSON Formatter 没问题，但上生产常被忽略三点：

• 日志文件不能被多个进程同时写（比如 gunicorn 多 worker），否则 JSON 行会错乱——必须用 RotatingFileHandler + delay=True，或改用 QueueHandler + 单独写入进程
• 每行一个 JSON 是业界共识（方便 Logstash、Fluentd 解析），所以不要用 indent=2，也别把多条日志 dump 到一个大 JSON 数组里
• 如果日志量大，频繁调用 json.dumps() 有性能开销，可考虑用 ujson 替代标

  

  准库 json（需自行测兼容性）

JSON Formatter 不难写，难的是字段一致性、上下文注入时机、以及多进程下的输出可靠性——这三个地方出问题，日志就既不好查，也不好解析。