PAYATHON 2026

multiprocessing.Pool 中 Logger 为何触发 _thread.lock pickle 错误?

排障赵师傅

结论

让 DataProcessor 保存 logger 名称、日志级别和处理器标识等可序列化的配置,在工作进程中获取并配置 logger。如果多个进程需要向同一个文件写日志,可以用 QueueHandler 将日志发送到队列,再由主进程中的 QueueListener 统一写入文件。

Python 3.7 起,标准库 logging.Logger 已支持按名称进行 pickle。在常规 CPython 3.10 环境中,仅凭示例中的 self.logger = logging.getLogger("ProcessorLogger"),通常无法复现 _thread.lock 序列化错误。实际代码可能还持有日志包装器、handler、线程锁或其他不可序列化对象。

为什么 pool.map() 会涉及 pickle

Pool 需要将任务发送给工作进程。执行以下调用时:

pool.map(worker, tasks)

任务参数包含 DataProcessor 实例,因此实例状态也必须能够被 pickle。即使用 fork 启动进程,后续通过 Pool 任务队列提交的参数仍然需要序列化。

如果实例属性包含 threading.Lock、日志 handler,或间接引用这些资源的包装器,就可能触发错误。日志 handler 内部有线程锁,文件 handler 还管理着打开的文件。这些运行时资源不适合直接作为任务状态传递。

标准库 Logger 有特殊处理:pickle 保存的是通过 logging.getLogger(name) 找回 logger 的信息,不会复制它的 handler、文件和配置。因此,Logger 能被 pickle,并不代表子进程会获得父进程的日志配置。

可以先分别检查实际传入的对象:

import pickle

processor = DataProcessor("Proc-0")

pickle.dumps(processor.logger)
pickle.dumps(processor)
pickle.dumps((processor, 0))

如果 logger 能序列化,而整个实例失败,就继续检查实例的其他属性。如果最小示例全部通过,可以逐步加入实际代码中的包装器、handler 和业务对象,找出哪一部分引入了锁。仅凭 traceback 中的 _thread.lock,无法断定锁来自 logger。

同名 logger 不能提供独立配置

在同一个进程中,多次调用:

logging.getLogger("ProcessorLogger")

得到的都是同一个 Logger 对象。原示例中的所有处理器因此共享该 logger。任意实例调用 setLevel(),都会改变这个进程中其他实例使用的日志级别。

需要分别控制各处理器的日志级别时,可以使用不同名称:

logging.getLogger("ProcessorLogger.Proc-0")
logging.getLogger("ProcessorLogger.Proc-1")

如果只是处理器标识不同,可以共用 logger,通过 LoggerAdapter 或 extra 添加上下文字段,无需为每个实例单独配置。

原示例也只设置了日志级别,没有配置文件输出。setLevel(logging.INFO) 本身不会创建日志文件。

完整示例:子进程发送日志,主进程写文件

  1. DataProcessor 只保存名称和级别等数据。
  2. 用 Pool 的 initializer 为每个工作进程配置 QueueHandler。
  3. 主进程创建唯一的 FileHandler,通过 QueueListener 接收日志。
  4. 正常结束时,先等待工作进程退出,再停止日志监听器。

下面的示例显式使用 spawn,避免依赖从父进程继承的日志配置。请保存为 .py 文件运行。

import logging
import multiprocessing
from logging.handlers import QueueHandler, QueueListener


class DataProcessor:
    def __init__(self, name, log_level=logging.INFO):
        self.name = name
        self.log_level = log_level
        self.logger_name = f"ProcessorLogger.{name}"

    @property
    def logger(self):
        # 在当前进程中获取;实例本身不保存 Logger 或 Handler。
        return logging.getLogger(self.logger_name)

    def run(self, data):
        self.logger.debug("Starting task: %s", data)
        self.logger.info("%s is processing %s", self.name, data)
        return data * 2


def configure_worker(log_queue):
    root = logging.getLogger()

    for handler in root.handlers[:]:
        root.removeHandler(handler)
        handler.close()

    root.setLevel(logging.DEBUG)
    root.addHandler(QueueHandler(log_queue))


def worker(obj_and_data):
    processor, data = obj_and_data

    # 这些配置必须在实际执行任务的进程中应用。
    processor.logger.setLevel(processor.log_level)
    return processor.run(data)


def main():
    ctx = multiprocessing.get_context("spawn")
    log_queue = ctx.Queue()

    file_handler = logging.FileHandler(
        "processors.log",
        encoding="utf-8",
    )
    file_handler.setLevel(logging.DEBUG)
    file_handler.setFormatter(
        logging.Formatter(
            "%(asctime)s %(processName)s "
            "%(name)s %(levelname)s %(message)s"
        )
    )

    listener = QueueListener(
        log_queue,
        file_handler,
        respect_handler_level=True,
    )

    tasks = [
        (
            DataProcessor(
                f"Proc-{i}",
                logging.DEBUG if i == 0 else logging.INFO,
            ),
            i,
        )
        for i in range(5)
    ]

    listener.start()
    try:
        with ctx.Pool(
            processes=4,
            initializer=configure_worker,
            initargs=(log_queue,),
        ) as pool:
            results = pool.map(worker, tasks)

            # 正常结束时等待工作进程退出,再停止日志监听器。
            pool.close()
            pool.join()

        print(results)
    finally:
        listener.stop()
        file_handler.close()
        log_queue.close()
        log_queue.join_thread()


if __name__ == "__main__":
    multiprocessing.freeze_support()
    main()

QueueListener 在主进程中通过后台线程消费队列,只有它持有的 FileHandler 向 processors.log 写入日志。工作进程负责生成日志记录并放入队列。

Proc-0 使用 DEBUG 级别,其余处理器使用 INFO。文件 handler 允许 DEBUG 及以上级别的记录通过,所以不会过滤掉 Proc-0 的调试日志。

队列在创建工作进程时,通过 initializer 的 initargs 传入。不要将它保存在每个 DataProcessor 实例中,再随 pool.map() 的任务反复传递。

已有类必须保留 self.logger 时怎么办

如果现有接口必须保留 self.logger 实例属性,可以在 pickle 时排除 logger,反序列化时再重新获取:

def __getstate__(self):
    state = self.__dict__.copy()
    state.pop("logger", None)
    return state

def __setstate__(self, state):
    self.__dict__.update(state)
    self.logger = logging.getLogger(self.logger_name)
    self.logger.setLevel(self.log_level)

这段代码适用于直接保存 self.logger 的类,无需与上例的只读 logger property 同时使用。

它只恢复当前进程中的 logger 引用。工作进程的 QueueHandler 仍需通过 initializer 配置,实例中的其他不可序列化资源也要分别处理。不要在 __setstate__() 中反复添加 handler,否则同一进程多次接收任务后,可能出现重复日志。

使用时还需注意什么

  • 不要让多个进程各自创建 FileHandler 向同一个文件写日志。标准文件 handler 的线程锁无法协调不同进程,日志轮转时也容易发生竞争。需要集中写入时,应交给一个监听端。
  • 分别检查 logger 和 handler 的级别。记录可能在生成前被 logger 丢弃,也可能在输出时被 handler 过滤。父进程的配置不会通过 Logger 的 pickle 自动传到子进程。
  • 同一进程内,相同名称对应同一个 logger。上例通过不同的处理器名称区分配置。如果多个实例使用相同名称,却需要不同级别,应调整命名,或改用任务上下文控制。
  • 队列中的日志记录也需要序列化。使用 extra 时,不要放入锁、打开的文件或其他不可 pickle 的对象。
  • 关闭顺序会影响日志是否完整。上例先对工作进程调用 close()、join(),再调用 listener.stop()。如果强制终止进程或进程崩溃,尚未发送完成的日志仍可能丢失。不同进程的记录顺序也不保证与实际发生时间完全一致。

换用 dill 或 pathos 不能替代日志初始化和集中写入机制。即使某些对象可以序列化,仍需明确安排文件句柄、锁和 handler 在新进程中的使用方式。

备注:内容仅供参考。