17370845950

分布式系统中应为每条日志自动添加请求ID以实现链路追踪：通过中间件在请求入口生成唯一trace_id并绑定至contextvars，日志Filter动态注入，Formatter引用；异步/多线程需显式传递；推荐集成OpenTelemetry自动获取并格式化trace_id。

在分布式系统中，为每条日志自动添加请求 ID（或 trace_id）是实现请求链路追踪的关键。这样能将一次 HTTP 请求在多个服务、中间件、异步任务中的日志串联起来，快速定位问题。

使用中间件注入请求 ID（Web 框架场景）

以主流框架为例，在请求进入时生成唯一 ID，并绑定到当前上下文（如 thread local / contextvars），后续日志处理器可从中读取。

• Flask：用 before_request 生成 request_id，存入 flask.g 或自定义上下文管理器；日志格式中通过自定义 LoggerAdapter 或 Filter 注入该值。
• Django：借助 django.utils.log.RequestIDFilter（需配合 django-request-id 第三方包），或在中间件中设置 request.id，再通过 LogRecord 的 extra 参数透传。
• FastAPI/Starlette：利用 contextvars.ContextVar 存储 trace_id，在 ASGI 中间件中 set，在自定义 logging.Filter 中 get 并添加到 log record。

日志处理器动态注入 trace_id

不依赖框架特性的通用方式：编写一个 logging.Filter，在每条日志写入前尝试从当前上下文获取 trace_id。

• Python 3.7+ 推荐用 contextvars.ContextVar(str) 存储，它天然支持异步和多线程隔离。
• 定义全局 trace_id_var = ContextVar("trace_id", default=None)，在入口处（如中间件、装饰器）调用 trace_id_var.set(...)。
• 自定义 Filter 类重写 filter(self, record)，读取 trace_id_var.get()，赋值给 record.trace_id，再在 formatter 中用 %(trace_id)s 引用。

与 OpenTelemetry 集成（推荐生产环境）

若已接入 OpenTelemetry（OTel），trace_id 可直接从当前 span 获取，无需手动维护。

• 安装 opentelemetry-instrumentation-logging（或手动在 logging filter 中调用 trace.get_current_span().get_span_context().trace_id）。
• 注意 trace_id 默认是 128-bit 十六进制整数，需转为 32 位小写字符串（format_trace_id(span_context.trace_id)）才便于阅读和日志搜索。



• 确保日志采集器（如 Loki、ELK）能识别 trace_id 字段并建立与链路系统的关联（例如通过 Jaeger UI 点击跳转）。

异步任务与子线程中的延续

请求 ID 不会自动跨线程或跨协程传播，必须显式传递。

• 使用 concurrent.futures.ThreadPoolExecutor 时，在 submit 前捕获当前 trace_id_var.get()，并在子线程中 set。
• 对 Celery 任务，可在发送任务时把 trace_id 作为参数或 header 传入，任务函数开头立即 set 到 contextvar。
• asyncio 场景下，ContextVar 天然支持 task 隔离，但需确保所有协程都运行在同一个 event loop 上——一般没问题；若用 run_in_executor，仍需手动传递。

关键是统一上下文载体（推荐 contextvars）、尽早注入、全程透传、日志格式对齐。只要 trace_id 出现在每条关键日志里，配合支持结构化日志的收集系统，就能真正实现“一键溯源”。