多进程同时写日志会乱吗？并发日志的正确做法是什么？

简化版

logging 模块是线程安全的（每个 Handler 内部有一把锁，保证同一进程内的多个线程不会写串），但它不是进程安全的——多个进程各自持有自己的锁，互相之间毫无约束。多进程写同一个文件时会出两类问题：① 单条日志内容交错（一条长日志被另一个进程的输出插进来切成两半）；② 日志轮转时互相踩踏（进程 A 把 app.log 改名成 app.log.1 的瞬间，进程 B 还持有旧文件的 fd 继续往「已被改名的文件」里写，导致新日志写进了已归档的文件、或者直接丢失）。第一类问题在 Linux 上其实大多数时候不会发生——因为以 O_APPEND 模式打开的文件，单次小于 PIPE_BUF（通常 4096 字节）的 write 是原子的；但一旦某条日志超过这个大小（打印大 JSON、堆栈），交错就会真实出现。第二类问题则是必然的，RotatingFileHandler 在多进程下从来就不安全。标准解法是「单写者模式」：所有进程把日志记录通过队列发给一个专门的进程/线程，由它统一写文件——标准库直接提供了 logging.handlers.QueueHandler + QueueListener 这对组件。而容器时代更省事的做法是：谁都不写文件，直接写 stdout，把轮转和收集交给 Docker/K8s 的日志驱动（十二要素应用的原则）。核心记忆：logging 线程安全但不进程安全；多进程要么走队列汇总到单写者，要么各写各的文件，最省事的是写 stdout。

详细版

四种多进程日志方案对比：

方案	原理	安全性	代价
直接多进程写同一文件	各自 `O_APPEND`	⚠️ 短行侥幸安全、轮转必炸	——
每进程一个文件	`app.log.{pid}`	✅ 安全	文件多、查询要合并
QueueHandler + Listener	单写者	✅ 标准解法	多一个进程/线程
写 stdout 交给采集	12factor	✅ 容器首选	依赖运行时
`ConcurrentLogHandler`（第三方）	文件锁	✅	每条日志加锁，慢

import logging, logging.handlers, multiprocessing as mp, queue, sys, os

# ① ★标准解法：QueueHandler（工作进程）+ QueueListener（单写者）★
def worker_init(log_queue):
    """每个工作进程的初始化：只挂一个 QueueHandler"""
    root = logging.getLogger()
    root.handlers.clear()                          # ★清掉继承来的 handler★
    root.addHandler(logging.handlers.QueueHandler(log_queue))
    root.setLevel(logging.INFO)

def listener_process(log_queue):
    """独立的日志进程：真正写文件的只有它一个"""
    handler = logging.handlers.RotatingFileHandler(
        "app.log", maxBytes=50 << 20, backupCount=5, encoding="utf-8")
    handler.setFormatter(logging.Formatter(
        "%(asctime)s %(processName)s %(levelname)s %(name)s %(message)s"))
    listener = logging.handlers.QueueListener(log_queue, handler,
                                              respect_handler_level=True)
    listener.start()
    return listener

if __name__ == "__main__":
    log_queue = mp.Queue(-1)                       # ★-1 = 无界；生产建议给个上限★
    listener = listener_process(log_queue)
    with mp.Pool(4, initializer=worker_init, initargs=(log_queue,)) as pool:
        pool.map(do_work, tasks)
    log_queue.put_nowait(None)                     # 哨兵（QueueListener 内部用）
    listener.stop()                                # ★等队列里剩余日志写完★

# ② ★单进程内的多线程：logging 本来就安全，不需要额外处理★
#    但如果日志写入很慢（网络 handler），可以用 QueueHandler 把写入挪到后台线程：
que = queue.Queue(10000)                            # ★有界，防止无限堆积★
qh = logging.handlers.QueueHandler(que)
ql = logging.handlers.QueueListener(que, logging.StreamHandler(), )
ql.start()                                          # ★异步日志：业务线程不再被 IO 阻塞★

# ③ ★容器里最省事的做法：写 stdout★
logging.basicConfig(
    stream=sys.stdout,                              # ★不写文件★
    level=logging.INFO,
    format='{"ts":"%(asctime)s","lvl":"%(levelname)s","msg":"%(message)s"}',
)
# → 轮转、收集、切割全部交给 Docker/K8s 的日志驱动
# ★别忘了 PYTHONUNBUFFERED=1（否则 stdout 是全缓冲，日志迟迟不出现）

# ④ 每进程一个文件（简单粗暴但有效）
handler = logging.FileHandler(f"app.{os.getpid()}.log")

# ⑤ ★fork 后要重建 handler★（尤其是网络/文件 handler）
os.register_at_fork(after_in_child=lambda: logging.getLogger().handlers.clear())

# ⑥ 演示交错：超过 PIPE_BUF 的单次写不再原子
long_msg = "X" * 8000        # ★> 4096，多进程同时写会被切开交错★
logging.info(long_msg)

⚠️ 三个必须记住的机制：① logging 的线程安全靠的是「每个 Handler 一把 threading.RLock」——emit() 时先 acquire，所以同一进程内多线程写同一个 Handler 不会互相打断。但这把锁只在进程内有效：多进程各有各的锁对象，跨进程没有任何互斥。② 多进程直接写同一文件之所以「看起来能用」，是因为 O_APPEND 的原子性——POSIX 保证以 append 模式打开的文件，一次 write 系统调用（且长度不超过 PIPE_BUF，Linux 上通常 4096 字节）是原子的，不会与其他进程的写交错。所以短日志行侥幸安全，一旦某条日志超过 4KB（打印大 JSON、完整堆栈、SQL 语句）就会被切开、和别的进程的输出交织在一起。③ RotatingFileHandler 在多进程下必然出问题：轮转的过程是「关闭当前文件 → 把 app.log 改名成 app.log.1 → 新建 app.log」，而其他进程仍持有旧文件的 fd——它们会继续往「已经被改名的那个 inode」里写，导致新日志跑进了归档文件；更糟的是多个进程可能同时触发轮转，互相覆盖对方刚建好的文件，造成日志段整段丢失。

完整版教学

一、logging 的线程安全是怎么实现的

logging 的写入路径：
  logger.info("msg")
    → 检查级别（快速返回）
    → 创建 LogRecord
    → 逐个 handler 调用 handler.handle(record)
        → ★acquire()★   # 每个 Handler 有一把 threading.RLock
        → emit(record)   # 格式化 + 写入
        → ★release()★

  ★ 所以"同一个进程内、多个线程写同一个 Handler"是安全的：
    锁保证了"格式化 + 写入"这一整段是互斥的

  ★ 但这把锁保护不了：
    ✗ 多进程（各自有独立的锁对象，互不知情）
    ✗ 多个 Handler 写同一个文件（两个 Handler = 两把锁）
    ✗ 你自己绕过 logging 直接 write 到同一个文件

模块级的锁：
  logging._lock  保护 logger 字典、handler 列表这些全局结构
  → addHandler / getLogger 等配置操作是线程安全的
  ★ 但"配置日志"仍应该在★程序启动时一次性完成★，
    运行中动态改 handler 容易和正在写日志的线程打架

★ fork 与 logging 的死锁（和 fork 安全那题呼应）：
  线程 A 正在 logging（★持有 handler 锁★）
  主线程 fork()
  → 子进程里锁是"已锁定"状态，而持有它的线程不存在
  → 子进程第一次 logging.info() → ★永久死锁★
  ✓ Python 3.7+ 的 logging ★已经用 os.register_at_fork 注册了处理器★
    在 fork 前后 acquire/release 所有 handler 锁 → 大幅缓解了这个问题
  ★ 但第三方 handler（自定义的、SDK 的）不一定遵守这个约定

性能开销（★经常被低估★）：
  一条 logging.info 的成本 ≈ 5~50μs（取决于 handler 和格式化）
    - 级别检查：~0.1μs（★被过滤掉的日志几乎零成本★）
    - 创建 LogRecord：~2μs
    - 格式化：~5μs（★%s 的惰性求值很重要★）
    - 写文件：~5μs（有缓冲）/ 写网络：★毫秒级★
  → 高频路径上每秒几十万条日志会明显拖慢业务
  ✓ 用 logger.isEnabledFor(logging.DEBUG) 包住昂贵的日志构造
  ✓ ★永远用 logger.info("x=%s", x) 而不是 logger.info(f"x={x}")★
    前者只有真正要输出时才格式化；f-string ★无论如何都会先算出来★

logging 的线程安全靠的是每个 Handler 一把 threading.RLock：handle() 时先 acquire，保证「格式化 + 写入」这一整段互斥。但这把锁保护不了多进程（各进程有独立的锁对象、互不知情），也保护不了「两个 Handler 写同一个文件」的情况。这里和 fork 安全那题呼应：线程正持有 handler 锁时 fork，子进程里这把锁永远是「已锁定」，第一次 logging.info() 就永久死锁——好在 Python 3.7+ 的 logging 已经用 os.register_at_fork 注册了处理器，在 fork 前后 acquire/release 所有 handler 锁，大幅缓解了这个问题（但第三方 handler 不一定遵守）。性能上要记住两条：被级别过滤掉的日志几乎零成本（所以 logger.debug 留在代码里没关系），以及永远用 logger.info("x=%s", x) 而不是 f-string——前者只有真要输出时才格式化，而 f-string 无论日志级别如何都会先把字符串算出来。

二、多进程写同一个文件：什么时候会出问题

情况一：★追加写的原子性（大多数时候侥幸安全）★
  以 O_APPEND 打开的文件，POSIX 保证：
    "定位到文件末尾 + 写入" 是★一次原子操作★
  → 两个进程同时 write，不会覆盖对方，只会一前一后

  ★ 但有长度限制：
    Linux 上单次 write 的原子性保证约为 ★PIPE_BUF = 4096 字节★
    （对普通文件，实际行为取决于文件系统，但 4KB 是通行的安全线）
  → 日志行 < 4KB：★侥幸安全★（这就是"多进程写日志好像没问题"的原因）
  → 日志行 > 4KB：★会被切开★，和其他进程的输出交织
     常见触发：打印大 JSON、完整堆栈、SQL 语句、request/response body

  实测现象：
    2026-08-01 INFO 开始处理 {"a": 1, "b": 22026-08-01 ERROR 另一个进程的日志
    ...2, ...}                      ← ★一条日志被劈成两半★

  ★ 还有一个前提：Python 的 FileHandler 默认是★行缓冲/全缓冲★的，
    多条日志可能被合并成一次 write（更容易超过 4KB）
    → logging 的 StreamHandler 每次 emit 后会 flush，所以基本是"一条一次 write"

情况二：★日志轮转（必然出问题）★
  RotatingFileHandler 的轮转过程：
    ① 检查文件大小超过 maxBytes
    ② 关闭当前文件
    ③ ★os.rename("app.log", "app.log.1")★
    ④ 新建并打开 app.log

  多进程下会发生什么：
    进程 A 执行到 ③，把 app.log 改名成 app.log.1
    进程 B ★仍然持有旧文件的 fd★（fd 指向 inode，改名不影响它）
    → B 继续写 → ★新日志写进了 app.log.1（已归档文件）★
    → 更糟：B 也触发轮转 → ★把 A 刚建的 app.log 又改名了★
    → 结果：日志段丢失、归档文件里混着新日志、backupCount 计数错乱

  ★ 结论：RotatingFileHandler / TimedRotatingFileHandler ★在多进程下从来就不安全★
    （官方文档明确说明了这一点）

情况三：★缓冲与丢失★
  进程被 kill -9 → ★缓冲区里的日志永久丢失★
  fork 时缓冲区被复制 → ★同一条日志被写两次★（fork 前要 flush）

三种错误现象的对应关系：
  ┌────────────────────────┬──────────────────────────────┐
  │ 现象                    │ 原因                          │
  ├────────────────────────┼──────────────────────────────┤
  │ 单条日志被切成两半       │ ★> 4KB 的写不再原子★          │
  │ 日志整段消失            │ ★轮转竞态★（被改名/覆盖）      │
  │ 归档文件里有新日志       │ ★进程持有旧 fd 继续写★        │
  │ 同一条日志出现两次       │ fork 前没 flush 缓冲区         │
  │ 崩溃后最近的日志没了     │ 缓冲区没落盘（SIGKILL）        │
  └────────────────────────┴──────────────────────────────┘

多进程写同一个文件的问题要分三种情况看。情况一是内容交错：以 O_APPEND 打开的文件，POSIX 保证「定位到末尾 + 写入」是一次原子操作，所以两个进程同时 write 不会互相覆盖——但这个原子性有长度限制（Linux 上约 PIPE_BUF = 4096 字节）。这就解释了为什么「多进程写日志好像没问题」：短日志行侥幸安全，一旦某条超过 4KB（大 JSON、完整堆栈、SQL）就会被切开并与其他进程的输出交织。情况二是日志轮转，这是必然出问题的：轮转过程是「关闭 → os.rename("app.log", "app.log.1") → 新建」，而其他进程仍持有旧文件的 fd（fd 指向 inode，改名不影响它），于是继续往已归档的文件里写；更糟的是多个进程可能同时触发轮转、互相覆盖对方刚建的文件，导致整段日志丢失——官方文档明确说明 RotatingFileHandler 在多进程下不安全。情况三是缓冲：kill -9 会丢缓冲区里的日志，fork 前没 flush 会让同一条日志被写两遍。

三、标准解法：QueueHandler + QueueListener

核心思想：★单写者模式★——把"多个进程写一个文件"变成"多个进程写队列、一个写者写文件"

  工作进程 A ──┐
  工作进程 B ──┼──► ★multiprocessing.Queue★ ──► ★QueueListener（单写者）★ ──► 文件
  工作进程 C ──┘        （只传 LogRecord）              （唯一持有 handler）

  ★ 好处：
    ① 只有一个进程碰文件 → ★轮转、格式化、交错问题全部消失★
    ② 工作进程的日志调用变成"往队列扔一下"→ ★不被 IO 阻塞★
    ③ 可以在 listener 里统一加工（脱敏、采样、路由到不同目标）

完整实现（★可直接抄★）：
  import logging, logging.handlers, multiprocessing as mp

  def configure_worker(q):
      """★每个工作进程调用一次★"""
      root = logging.getLogger()
      root.handlers.clear()                    # ★关键：清掉 fork 继承来的 handler★
      root.addHandler(logging.handlers.QueueHandler(q))
      root.setLevel(logging.INFO)              # ★级别过滤在工作进程做，减少队列流量★

  def start_listener(q):
      fh = logging.handlers.RotatingFileHandler("app.log", maxBytes=50<<20, backupCount=5)
      fh.setFormatter(logging.Formatter("%(asctime)s %(processName)s %(levelname)s %(message)s"))
      lis = logging.handlers.QueueListener(q, fh, respect_handler_level=True)
      lis.start()
      return lis

  if __name__ == "__main__":
      q = mp.Queue(50000)                      # ★有界！防止日志暴涨吃光内存★
      lis = start_listener(q)
      try:
          with mp.Pool(4, initializer=configure_worker, initargs=(q,)) as pool:
              pool.map(work, tasks)
      finally:
          lis.stop()                           # ★把队列里剩下的日志写完再退出★

★ 六个实现细节（做不对就会踩坑）：
  ① ★队列必须有界★：无界队列在日志暴增时会吃光内存
     有界队列满了怎么办？QueueHandler 默认会阻塞 → ★业务被日志拖慢★
     ✓ 自定义：满了就丢弃 DEBUG/INFO，只保留 WARNING 以上
       class DroppingQueueHandler(logging.handlers.QueueHandler):
           def enqueue(self, record):
               try: self.queue.put_nowait(record)
               except queue.Full: pass          # ★丢弃而不是阻塞业务★
  ② ★LogRecord 要能被 pickle★
     QueueHandler.prepare() 已经帮你做了：★先格式化 message、丢掉 exc_info 对象★
     但如果你在 record 上塞了不可 pickle 的对象（如连接、锁）→ 报错
  ③ ★级别过滤放在工作进程★：别把 DEBUG 全扔进队列再由 listener 过滤
  ④ ★listener 必须 stop()★：否则队列里剩余的日志丢失
  ⑤ ★工作进程要 clear() 继承来的 handler★（fork 模式下会继承父进程的 handler，
     否则会出现"既走队列又直接写文件"的双写）
  ⑥ Windows/spawn 模式下，queue 必须作为参数显式传给子进程

★ 单进程多线程也能用这套：把慢 handler（网络、数据库）挪到后台线程
  que = queue.Queue(10000)                      # ★普通 Queue 就够★
  listener = logging.handlers.QueueListener(que, slow_http_handler)
  → 业务线程只管入队（微秒级），网络 IO 在后台线程做
  → ★这就是"异步日志"★

标准解法是单写者模式：所有进程把 LogRecord 扔进队列，由唯一的 QueueListener 写文件——这样轮转、格式化、交错问题全部消失，而且工作进程的日志调用变成「往队列扔一下」，不再被 IO 阻塞。六个实现细节做不对就会踩坑：① 队列必须有界（无界队列在日志暴增时吃光内存；但有界队列满了 QueueHandler 默认会阻塞业务，所以生产上通常自定义成「满了就丢弃低级别日志」）；② LogRecord 要能 pickle（QueueHandler.prepare() 已经帮你把 message 预格式化、丢掉 exc_info 对象）；③ 级别过滤放在工作进程（别把 DEBUG 全扔进队列）；④ listener.stop() 必须调用，否则队列里剩余的日志丢失；⑤ 工作进程要 handlers.clear()，否则 fork 会继承父进程的 handler 造成「既走队列又直接写文件」的双写；⑥ spawn 模式下队列要显式传给子进程。同一套机制在单进程多线程下也有用——把慢 handler（网络、数据库）挪到后台线程，这就是异步日志。

四、多进程日志轮转的其他方案

方案对比（★按推荐度排序★）：

  ① ★写 stdout，轮转交给外部★（容器时代首选，见下一节）
     零竞态、零配置

  ② ★QueueHandler + QueueListener★（上一节）
     标准库自带，最通用

  ③ ★每进程一个文件★
     handler = FileHandler(f"/var/log/app/app-{os.getpid()}.log")
     优点：零竞态、实现最简单、性能最好
     缺点：文件数量多（worker 重启会产生新文件）、查询要合并
     ✓ 适合：worker 数量固定、有日志采集系统（ELK/Loki）统一收集
     ✓ 变体：按 worker 序号而不是 pid 命名（避免重启后堆积无数文件）

  ④ ★WatchedFileHandler + 外部 logrotate★（Unix 传统方案）
     WatchedFileHandler 每次写之前检查文件的 ★dev/inode 是否变了★
     → 如果 logrotate 把文件改名了，它会★自动重新打开★新文件
     → 配合系统的 logrotate（copytruncate 或 create 模式）
     ✓ 优点：轮转由成熟的外部工具做，多进程都能正确跟随
     ✗ 注意：★它解决的是"跟随轮转"，不解决"写入交错"★（>4KB 仍会交错）

  ⑤ ★第三方 ConcurrentRotatingFileHandler★（concurrent-log-handler 包）
     用★文件锁★（fcntl/msvcrt）保证轮转和写入的互斥
     ✓ 真正的多进程安全（含轮转）
     ✗ ★每条日志都要加解锁★→ 高频日志下性能明显下降
     ✓ 适合：日志量不大、又必须多进程写同一文件的场景

  ⑥ ★syslog / journald★
     SysLogHandler 发到本地 syslog，由 syslog 守护进程统一落盘
     ✓ 天然单写者、成熟稳定
     ✗ 有长度限制、格式受限、多一个依赖

★ 绝对不要做的：
  ✗ 多进程共用 RotatingFileHandler（★官方明确说不安全★）
  ✗ 用 threading.Lock 保护多进程写入（★锁不跨进程★）
  ✗ 指望"日志量小就没事"（大 JSON 一条就超 4KB）

Gunicorn / uWSGI 的实践：
  Gunicorn: 每个 worker 是 fork 出来的 → ★共享父进程配置的 handler★
    ✓ 用 --access-logfile - --error-logfile -（★写 stdout★）
    ✓ 或在 post_fork hook 里给每个 worker 重新配置日志
  uWSGI: 有自己的 logger 体系（--logto、--log-master）
    ★--log-master 让 master 进程统一写日志★→ 本质也是单写者

多进程日志轮转有六种方案，按推荐度排序：写 stdout 交给外部（容器首选，零竞态）> QueueHandler + Listener（标准库自带、最通用）> 每进程一个文件（零竞态、性能最好，但文件多、要靠采集系统合并）> WatchedFileHandler + 外部 logrotate（它每次写前检查文件的 dev/inode 是否变化，如果被 logrotate 改名就自动重新打开——注意它只解决「跟随轮转」，不解决写入交错）> 第三方 ConcurrentRotatingFileHandler（用文件锁保证互斥，真正安全但每条日志都要加解锁、高频下性能明显下降）> syslog/journald（天然单写者）。三件绝对不要做的事：多进程共用 RotatingFileHandler（官方明确说不安全）、用 threading.Lock 保护多进程写入（锁不跨进程）、以及指望「日志量小就没事」（一条大 JSON 就超 4KB）。Gunicorn 的推荐配置是 --access-logfile -（写 stdout），uWSGI 的 --log-master 本质也是单写者。

五、容器时代的正解：写 stdout

十二要素应用（12factor）的日志原则：
  ★"应用不应该关心日志的路由和存储，它只负责把日志作为事件流写到 stdout"★

  应用 → stdout → 容器运行时捕获 → 日志驱动/采集器 → 存储与查询
                    (Docker json-file / K8s + Fluent Bit / Loki / ELK)

  ★ 好处：
    ① ★零竞态★：每个容器一个进程写 stdout，没有多进程抢文件的问题
       （即使容器内有多进程，stdout 的 fd 是同一个，且 O_APPEND 语义）
    ② 轮转、压缩、保留策略★由运行时统一管理★（不用改代码）
    ③ 应用不需要挂载日志卷、不需要考虑磁盘满
    ④ 采集器统一加上 pod/container/namespace 等元数据

  配置：
    logging.basicConfig(stream=sys.stdout, level=logging.INFO, format=...)
    ★ 别忘了 ENV PYTHONUNBUFFERED=1★（否则 stdout 连管道是全缓冲，
      日志要攒够 8KB 才出现，kubectl logs 长时间空白）

★ 结构化日志（配套的最佳实践）：
  纯文本日志在采集端要靠正则解析，脆弱且慢
  → 直接输出 ★JSON 一行一条★，采集器零解析成本
  import json, logging
  class JsonFormatter(logging.Formatter):
      def format(self, record):
          return json.dumps({
              "ts": self.formatTime(record, "%Y-%m-%dT%H:%M:%S%z"),
              "level": record.levelname,
              "logger": record.name,
              "pid": record.process,
              "msg": record.getMessage(),
              "trace_id": getattr(record, "trace_id", None),   # ★上下文★
              **({"exc": self.formatException(record.exc_info)} if record.exc_info else {}),
          }, ensure_ascii=False)                                # ★中文不转义★
  → 或直接用 structlog / python-json-logger

★ 上下文注入（分布式追踪的基础）：
  用 contextvars 在协程/线程间传递 request_id，通过 Filter 注入到每条日志：
  request_id = contextvars.ContextVar("request_id", default="-")
  class ContextFilter(logging.Filter):
      def filter(self, record):
          record.trace_id = request_id.get()
          return True
  handler.addFilter(ContextFilter())
  → ★一个请求的所有日志能被串起来★（多进程/多线程下尤其重要）

  ★ contextvars 的优势：★协程安全★（threading.local 在 asyncio 里会串）

stdout 方案的边界：
  ✗ 日志量极大（每秒几十万条）时，stdout + 采集可能成为瓶颈
    → 考虑直接写本地文件 + 高性能采集（Fluent Bit tail）
  ✗ 需要按业务分文件（audit.log / access.log 分开）
    → 用不同的 logger + 在采集端按字段路由（★而不是应用端分文件★）
  ✗ 非容器的传统部署 → 回到 QueueListener 或 logrotate 方案

容器时代的正解来自十二要素应用的日志原则：应用不应该关心日志的路由和存储，只负责把日志作为事件流写到 stdout。好处是零竞态（不用管多进程抢文件）、轮转和保留策略由运行时统一管理（不用改代码）、应用不需要挂日志卷、采集器还会自动补上 pod/container 等元数据。配置极简，但千万别忘 PYTHONUNBUFFERED=1——否则 stdout 连着管道是全缓冲，日志要攒够 8KB 才出现，kubectl logs 会长时间空白。配套的两个最佳实践：结构化日志（直接输出 JSON 一行一条，采集端零解析成本，注意 ensure_ascii=False 让中文不被转义）和上下文注入（用 contextvars 传递 request_id，通过 Filter 注入每条日志，把一个请求的所有日志串起来——contextvars 比 threading.local 更好，因为它协程安全）。这个方案的边界是：日志量极大时 stdout 可能成为瓶颈，需要按业务分文件时应该在采集端按字段路由而不是在应用端分文件。

六、性能、可靠性与实践清单

★ 日志的性能开销（高频路径上要注意）：
  被级别过滤掉的日志       ~0.1μs   ← ★几乎免费，debug 日志可以随便留★
  写内存队列（QueueHandler）~2μs
  写文件（有缓冲）          ~5~20μs
  ★写网络（HTTP/Syslog handler）★  ★毫秒级 → 必须异步化★

  ✓ 优化手段：
    ① ★用 %s 惰性格式化，不要用 f-string★
       logger.debug("data=%s", expensive_repr(obj))   # ★不输出时不会调用★
       logger.debug(f"data={expensive_repr(obj)}")    # ✗ ★总是会调用★
    ② 昂贵的日志用 isEnabledFor 包住
       if logger.isEnabledFor(logging.DEBUG):
           logger.debug("state=%s", dump_full_state())
    ③ 高频日志采样：每 N 条记一条，或用 RateLimitFilter
    ④ 慢 handler 一律走 QueueHandler 异步化

★ 可靠性权衡（★没有免费的午餐★）：
  ┌────────────────┬──────────────┬──────────────────────────┐
  │ 方案            │ 崩溃时        │ 说明                      │
  ├────────────────┼──────────────┼──────────────────────────┤
  │ 同步写 + flush  │ ★不丢★       │ 最慢（每条一次系统调用）   │
  │ 同步写 + 缓冲   │ 丢最后几 KB   │ 默认行为                  │
  │ 队列异步        │ ★丢队列里的★ │ 最快，但 kill -9 会丢     │
  │ 有界队列 + 丢弃 │ 丢被丢弃的    │ ★保护业务不被日志拖垮★    │
  └────────────────┴──────────────┴──────────────────────────┘
  → ★审计日志/交易日志要同步 + flush；普通业务日志用异步★

★ 最终实践清单：
  □ 明确"我是不是多进程"——是就★不要多进程共用 RotatingFileHandler★
  □ 容器里：★写 stdout + PYTHONUNBUFFERED=1 + JSON 格式★
  □ 非容器多进程：★QueueHandler + QueueListener★，队列★有界★
  □ 工作进程里 ★handlers.clear()★ 再挂 QueueHandler（防 fork 双写）
  □ ★listener.stop()★ 放在退出路径上（保证剩余日志写完）
  □ 级别过滤在源头做，别把 DEBUG 全扔进队列
  □ ★用 %s 惰性格式化★，慢 handler 异步化
  □ 注入 request_id/trace_id（用 ★contextvars★，不要用 threading.local）
  □ 日志里★不要打印敏感信息★（密码、token、身份证）——加脱敏 Filter
  □ 轮转策略：容器交给运行时；传统部署用 ★logrotate + WatchedFileHandler★
  □ ★演练★：多进程压测时看日志有没有交错、轮转时有没有丢段

性能上要记住三条：被级别过滤掉的日志几乎免费（所以 debug 日志可以放心留在代码里）、写网络的 handler 是毫秒级、必须异步化、以及永远用 logger.info("x=%s", x) 的惰性格式化（f-string 无论是否输出都会先求值，昂贵的 repr 会白白执行）。可靠性方面没有免费的午餐：同步写加 flush 最可靠但最慢、队列异步最快但 kill -9 会丢队列里的内容——审计和交易日志要同步 + flush，普通业务日志用异步。最终清单里最关键的五条：容器里写 stdout + PYTHONUNBUFFERED=1 + JSON 格式、非容器多进程用 QueueHandler + 有界队列、工作进程先 handlers.clear() 防 fork 双写、listener.stop() 放在退出路径上、以及用 contextvars 注入 trace_id。最后别忘了演练——多进程压测时实际看一眼日志有没有交错、轮转时有没有丢段。

记忆钩子：「★logging 是线程安全的（每个 Handler 一把 RLock）但不是进程安全的★——多进程各有各的锁、互不知情。多进程写同一文件有两类问题：①★内容交错★：O_APPEND 保证『定位末尾+写入』原子，但★只在单次 write 不超过约 4KB（PIPE_BUF）时★，所以短日志侥幸安全、★一条大 JSON 或完整堆栈超过 4KB 就会被切开交织★；②★轮转必炸★：RotatingFileHandler 的轮转是『关闭→rename→新建』，其他进程★仍持有旧文件的 fd★（fd 指向 inode、改名不影响），于是继续往已归档文件里写，多个进程还可能同时轮转互相覆盖 → ★整段日志丢失★（官方明确说它多进程不安全）。★标准解法是单写者模式：QueueHandler（各进程）+ QueueListener（唯一写者）★，六个细节要做对——★队列必须有界★（满了默认会阻塞业务，生产上改成丢弃低级别）、LogRecord 要可 pickle（prepare 已预格式化 message）、级别过滤放在源头、★listener.stop() 必须调★、★工作进程先 handlers.clear() 防 fork 继承造成双写★、spawn 下队列要显式传。★容器时代更省事：谁都不写文件，直接写 stdout 交给运行时轮转和采集（12factor），配 PYTHONUNBUFFERED=1 + JSON 结构化 + contextvars 注入 trace_id★（contextvars 比 threading.local 好，因为它★协程安全★）。其他方案：每进程一个文件（零竞态最简单）、★WatchedFileHandler + 外部 logrotate★（靠比对 dev/inode 自动重开文件，但★只解决跟随轮转、不解决交错★）、第三方 ConcurrentRotatingFileHandler（文件锁，安全但每条都加锁很慢）。性能三条：★被级别过滤的日志几乎免费★、写网络的 handler 是毫秒级必须异步、★永远用 logger.info(‘x=%s’, x) 而不是 f-string★（后者无论如何都会先求值）。还要记得 fork 时若有线程持有 handler 锁会死锁——★3.7+ 的 logging 已用 register_at_fork 缓解，但第三方 handler 不一定★。」

七、常见误区与追问

误区：logging 是线程安全的，所以多进程写同一个日志文件也没问题。 线程安全和进程安全是两回事。logging 的线程安全靠的是「每个 Handler 内部一把 threading.RLock」——它只在同一个进程内有效；多进程各自拥有独立的 Handler 对象和锁对象，互相之间毫无约束。多进程写同一个文件之所以「看起来能用」，靠的是操作系统层面 O_APPEND 的原子性保证（单次 write 不超过约 4KB 时不会交错），这是侥幸而不是设计。一旦某条日志超过这个长度（打印大 JSON、完整异常堆栈、SQL 语句），就会被切开、和其他进程的输出交织；而日志轮转在多进程下则是必然出问题，与日志长度无关。
误区：多进程用 RotatingFileHandler，只要日志量小就不会出问题。 轮转的竞态和日志量大小无关，只和「是否发生轮转」有关。轮转过程是「关闭当前文件 → os.rename("app.log", "app.log.1") → 新建 app.log」，问题在于其他进程仍持有旧文件的文件描述符——fd 指向的是 inode，改名不会让它失效，所以那些进程会继续往已经被归档的文件里写，直到它们自己也触发轮转才会重新打开。更糟的是多个进程可能几乎同时检测到超限并各自执行轮转，后执行的会把先执行者刚创建的新文件也改名，造成整段日志丢失、backupCount 计数错乱。Python 官方文档明确指出 RotatingFileHandler/TimedRotatingFileHandler 不支持多进程。正确做法是单写者（QueueListener）、每进程一个文件、或 WatchedFileHandler + 外部 logrotate。
误区：用 threading.Lock 或 multiprocessing.Lock 保护日志写入就安全了。 threading.Lock 完全不跨进程——fork 后每个进程拿到的是各自的锁副本，加了等于没加。multiprocessing.Lock 确实能跨进程互斥，但用它保护日志有三个问题：① 每条日志都要跨进程加解锁（涉及信号量系统调用），高频日志下性能损失显著；② 它解决不了轮转竞态——即使写入互斥了，一个进程 rename 文件后其他进程的 fd 依然指向旧 inode；③ 锁必须在进程创建前建好并显式传递（spawn 模式下尤其麻烦），而且持锁进程崩溃会导致所有进程卡死。真正解决问题的思路是消除竞争（单写者或每进程一个文件），而不是加锁竞争。如果确实必须多进程写同一文件，用成熟的 concurrent-log-handler（它用的是文件锁并处理了轮转）。
误区：logger.info(f"处理了 {expensive_calc()} 条") 和 logger.info("处理了 %s 条", expensive_calc()) 效果一样。 性能上差别巨大。f-string 是在调用 logger.info 之前就完成求值和拼接的——无论日志级别是否会输出这条记录，expensive_calc() 都会被执行、字符串都会被拼出来。而 %s 形式把参数原样传给 logging，只有当这条记录真的要被输出时才在 Handler 里做格式化——被级别过滤掉的日志几乎零成本（约 0.1μs）。在高频路径上放一条带 f-string 的 logger.debug，即使线上是 INFO 级别，那个昂贵的计算依然每次都在跑。对特别昂贵的日志（序列化整个对象、查数据库），还应该用 if logger.isEnabledFor(logging.DEBUG): 包起来。这也是为什么各种 lint 工具（如 pylint 的 logging-fstring-interpolation）会对日志里的 f-string 告警。
误区：改用 QueueHandler 后日志就万无一失了。 有三个必须处理的细节。① 队列必须有界：mp.Queue(-1) 是无界的，日志暴增（比如某个异常疯狂刷屏）时会吃光内存；但有界队列满了之后 QueueHandler 默认会阻塞——日志反过来拖垮了业务。生产环境通常要自定义 enqueue()：满了就丢弃 DEBUG/INFO、只保留 WARNING 以上。② 必须调 listener.stop()：否则进程退出时队列里尚未写出的日志全部丢失，而这往往正是崩溃前最关键的那几条。③ 工作进程要先 handlers.clear()：fork 模式下子进程会继承父进程配置好的所有 handler，如果不清掉就直接加 QueueHandler，会变成「既往队列扔一份、又自己直接写文件一份」的双写，反而制造了新的多进程写文件问题。另外要记住异步日志的固有代价：kill -9 时队列里的日志必然丢失，审计类日志应该同步写并 flush。
追问：为什么多进程追加写日志「大多数时候」不会乱？ 因为 logging 的 FileHandler 以追加模式（O_APPEND） 打开文件，而 POSIX 保证：对以 O_APPEND 打开的文件，「移动到文件末尾」和「写入数据」是一次原子操作——内核在写之前会先原子地把偏移量设到当前文件末尾，因此两个进程同时写不会互相覆盖，只会一前一后。但这个原子性有长度上限：Linux 上对管道保证的是 PIPE_BUF（通常 4096 字节），对普通文件的行为虽然依赖文件系统，但4KB 是通行的安全线——超过这个长度的单次 write 可能被内核拆成多次，中间就可能插入其他进程的数据。所以「短日志行不会乱」是真的，但打印大 JSON、完整堆栈、长 SQL 时就会被切开交织。另外 StreamHandler 每次 emit 后会 flush，基本保证「一条日志 = 一次 write」，这也是它侥幸安全的前提；如果你自己缓冲多条再写，超过 4KB 的概率就大大增加了。
追问：WatchedFileHandler 解决了什么问题，它和 RotatingFileHandler 有什么不同？ RotatingFileHandler 自己负责轮转（检查大小 → rename → 新建），所以多进程下会互相踩踏。WatchedFileHandler 不做轮转，它做的是「跟随轮转」：每次写日志前检查当前文件路径对应的 st_dev 和 st_ino 是否和自己打开的那个文件一致——如果外部工具（logrotate）把文件改名或删除了，inode 就对不上，它会自动关闭旧 fd、重新打开该路径。这样轮转由成熟的系统工具统一执行（logrotate 用 create 模式即可），所有进程都能正确切换到新文件，彻底避免了多进程各自轮转的竞态。它的边界要清楚：它只解决「跟随轮转」，不解决「写入交错」——超过 4KB 的日志行在多进程下依然会交织；而且它只在 Unix 上有意义（Windows 上文件被打开时无法改名）。传统（非容器）部署的多进程日志方案，WatchedFileHandler + logrotate 是最稳妥的组合。
追问：为什么容器里推荐写 stdout 而不是写文件？ 这来自十二要素应用的日志原则：应用应该把日志当作事件流写到 stdout，不关心路由和存储。好处有四点：① 零竞态——不需要处理多进程抢文件、轮转互相踩踏的问题；② 职责分离——轮转、压缩、保留期限、切割由容器运行时或采集器（Docker 的 json-file 驱动、K8s + Fluent Bit）统一管理，改策略不用改代码、不用重启应用；③ 免运维——应用不需要挂载日志卷，也不用担心把容器磁盘写满；④ 自动打标——采集器会自动补上 pod、namespace、container 等元数据，比应用自己写更准确。实践上要配套三件事：PYTHONUNBUFFERED=1（否则 stdout 连着管道是全缓冲，kubectl logs 会长时间空白）、JSON 结构化输出（采集端零解析成本，ensure_ascii=False 避免中文被转义）、以及用 contextvars 注入 trace_id（把一次请求的所有日志串起来）。它的边界是：日志量极大（每秒几十万条）时 stdout 管道可能成为瓶颈，这时才考虑写本地文件 + 高性能采集。

八、加强记忆

logging 是线程安全的（每个 Handler 一把 RLock）但不是进程安全的——多进程各有各的锁、互不知情。多进程写同一文件有两类问题：① 内容交错——O_APPEND 保证「定位末尾 + 写入」原子，但只在单次 write 不超过约 4KB（PIPE_BUF）时成立，所以短日志侥幸安全，一条大 JSON 或完整堆栈超过 4KB 就会被切开并与其他进程的输出交织；② 轮转必炸——RotatingFileHandler 的轮转是「关闭 → rename → 新建」，而其他进程仍持有旧文件的 fd（fd 指向 inode、改名不影响它），于是继续往已归档文件里写，多个进程还可能同时轮转、互相覆盖，导致整段日志丢失（官方明确说明它不支持多进程）。标准解法是单写者模式：QueueHandler（各工作进程）+ QueueListener（唯一写者），六个细节要做对——队列必须有界（满了默认会阻塞业务，生产上应改成丢弃低级别日志）、LogRecord 要可 pickle（prepare() 已预格式化 message）、级别过滤放在源头、listener.stop() 必须调用（否则丢失队列中剩余日志）、工作进程先 handlers.clear()（防止 fork 继承 handler 造成双写）、spawn 模式下队列要显式传递。容器时代更省事的做法是谁都不写文件、直接写 stdout，把轮转和采集交给运行时（12factor），配套 PYTHONUNBUFFERED=1 + JSON 结构化 + contextvars 注入 trace_id（contextvars 比 threading.local 好，因为它协程安全）。其他可选方案：每进程一个文件（零竞态、最简单）、WatchedFileHandler + 外部 logrotate（靠比对 st_dev/st_ino 自动重新打开文件，但只解决跟随轮转、不解决写入交错）、第三方 ConcurrentRotatingFileHandler（文件锁，安全但每条都加锁较慢）。性能三条：被级别过滤的日志几乎免费、写网络的 handler 是毫秒级必须异步化、永远用 logger.info("x=%s", x) 而不是 f-string（后者无论是否输出都会先求值）。最后别忘了 fork 时若有线程持有 handler 锁会导致子进程死锁——Python 3.7+ 的 logging 已用 register_at_fork 缓解，但第三方 handler 不一定。

简化版

详细版