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或空字符串