默认 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 不难写，难的是字段一致性、上下文注入时机、以及多进程下的输出可靠性——这三个地方出问题，日志就既不好查，也不好解析。
