Python 结构化日志实现技巧

结构化日志需通过loggeradapter注入动态上下文、用jsonformatter序列化为机器可读json、统一字段命名规范（如Event/duration_ms/Error_type）、并集成fastapi/django/celery等框架实现链路透传与事件关联。

python 结构化日志不是简单地把字典塞进 Logging.info()，而是让每条日志天然携带可解析的字段（如 user_id、request_id、status_code），便于后续过滤、聚合与告警。核心在于统一上下文注入、字段语义清晰、序列化可控，而非仅靠格式化字符串“模拟”结构。

用 LoggerAdapter 注入动态上下文

避免在每个 logger.info() 调用中重复传入公共字段（如请求 ID、用户 ID）。用 LoggerAdapter 封装 logger，自动注入运行时上下文：

• 定义适配器，重写 process() 方法，在日志记录前合并额外字段
• 结合 contextvars（Python 3.7+）存储请求级变量，确保异步/多线程安全
• 示例：在 FastAPI 中间件里设置 request_id，再通过 adapter 统一附加到所有日志

选对序列化方式：JSON 而非格式化字符串

结构化日志的本质是机器可读，不是人眼友好。别用 %(asctime)s - %(name)s - %(levelname)s - %(message)s 这类传统格式。

• 用 JsonFormatter（如 python-json-logger 库）将 LogRecord.__dict__ 或自定义 extra 字段转为 JSON 行
• 确保时间字段用 ISO8601 格式（datetime.now().isoformat()），不依赖 locale
• 避免在 message 字段拼接结构化内容；应把业务数据全放在 extra 里，让 formatter 处理输出

定义日志事件模式，约束字段命名与类型

没有规范的结构等于没有结构。团队需约定关键字段名和含义，例如：

立即学习“Python免费学习笔记（深入）”；

• event：必填，字符串，表示事件类型（如 "user_login"、"db_query_timeout"）
• level：用标准级别（"INFO"/"ERROR"），不自创
• duration_ms：数值型耗时，单位毫秒，便于统计 P95/P99
• error_type 和 error_message：仅在异常日志中出现，分离类型与描述

可用 Pydantic 模型做日志构造器，强制校验字段，避免拼写错误或类型混乱。

集成到主流框架：FastAPI / Django / Celery

结构化日志要落地，必须无缝嵌入实际运行环境：

• FastAPI：用中间件 + contextvars + LoggerAdapter 实现请求链路透传
• Django：覆写 LOGGING 配置，用 JsonFormatter 替换默认 Formatter，并为 django.request 等内置 logger 启用结构化输出
• Celery：在 task 的 __call__ 或 on_failure 回调中注入任务 ID、重试次数等字段，避免日志散落在不同 worker 上无法关联

不复杂但容易忽略。