Python并发日志需用contextvars/ThreadLocal/extra参数注入唯一ID，并通过Filter写入LogRecord、Formatter显式引用，避免手动拼接；排查须检查Filter添加位置、ID设置时机及Formatter字段一致性。
在Python并发程序中，日志无法准确关联到具体任务或请求，是排错最常见也最头疼的问题。根本原因在于多个线程/协程共享同一个Logger实例，而默认的LogRecord不携带上下文标识（如request_id、task_id、correlation_id），导致日志混杂、难以追踪执行流。
为每个并发单元注入唯一上下文ID
无论是多线程（threading）、多进程（multiprocessing）还是异步协程（asyncio），都需要在任务启动时生成并绑定一个轻量级唯一标识，贯穿该任务生命周期。
-
线程场景：使用
threading.local()存储当前线程的request_id，再通过自定义Filter将其注入LogRecord -
协程场景：用
contextvars.ContextVar（Python 3.7+）定义ctx_request_id = ContextVar('request_id', default=None)，在任务入口ctx_request_id.set(...)，Filter中取值写入日志 -
进程场景：无法跨进程共享变量，需在子进程启动时显式传入
process_id或task_id，并通过logging.LoggerAdapter或extra参数带入
统一日志格式，强制输出上下文字段
仅注入ID不够，必须确保它稳定出现在每条日志中。推荐在Formatter中显式引用自定义字段，避免依赖%(message)s拼接——后者易遗漏或格式错乱。
- 配置
Formatter时使用%(request_id)s、%(task_id)s等占位符（前提是Filter已将这些字段写入record） - 示例格式字符串：
'[%(asctime)s][%(levelname)-5s][%(request_id)s][%(name)s] %(message)s' - 避免在业务代码中手动
logger.info(f"[{req_id}] ...")，这会绕过上下文机制且增加维护成本
适配主流并发模型的最小可行代码片段
不同模型初始化方式差异大，但核心逻辑一致：任务创建 → 绑定ID → 日志自动携带。以下是可直接复用的关键片段：
立即学习“Python免费学习笔记（深入）”；
-
asyncio + contextvars：
from contextvars import ContextVar; req_id_var = ContextVar('req_id', default='')；在协程入口调用req_id_var.set(generate_id())；Filter中record.request_id = req_id_var.get() -
threading + local：
local_data = threading.local()；在线程函数开头设local_data.req_id = generate_id()；Filter中record.request_id = getattr(local_data, 'req_id', 'N/A') -
concurrent.futures：用
submit(fn, *args, **kwargs)时，把req_id作为参数传入fn，再通过LoggerAdapter包装logger，实现logger.info("msg", extra={'request_id': req_id})
排查时优先检查三个断点
日志关联失效，90%问题出在这三处，按顺序验证能快速定位：
-
Filter是否被正确添加到Handler：检查
handler.addFilter(MyContextFilter())，而非logger.addFilter(...)（后者对Handler无效） -
上下文变量是否在日志触发前已设置：比如协程中
req_id_var.set(...)写在await之后，会导致后续日志拿不到值 -
Formatter是否声明了对应字段：若Filter写了
record.correlation_id，但Formatter里是%(request_id)s，该字段将显示为None或空字符串
