Python 日志库怎么选：六款主流日志库横向对比

Python 日志库选型中文指南：标准库 logging、Loguru、Structlog、Eliot、Logbook、Picologging 六款库的功能、性能、适用场景横向对比，附选型决策建议与观测云平台接入方案。

观测云编辑部 2026-08-26 7 分钟阅读更新于 2026-08-26

业务日志已经改成 JSON，第三方库却还在输出另一套格式；事件循环变慢，换一个更快的日志 API 也没有改变阻塞的文件写入。Python 日志库的选择，往往要同时考虑调用方式、输出结构和现有框架的集成。

标准库 logging 是容易衔接现有依赖的起点。Loguru 把轮转、保留与序列化集中在 sink 配置中；structlog 用事件字典和处理器链组织字段；Picologging 关注日志实现本身的开销。Eliot 的动作树与 Logbook 的 handler 栈，则适合不同的程序结构。下面比较这些机制，不用一个无关负载的性能排名替代选择。

六款日志库快速对比

库	定位	结构化	配置复杂度	性能	适合谁
logging（标准库）	通用基础	需借助 formatter	中高	依负载验证	所有项目的默认选择
Loguru	开箱即用	serialize 一键 JSON	极低	依负载验证	中小项目、脚本、追求效率的团队
Structlog	结构化专家	原生结构化	中	依负载验证	微服务、对字段规范要求高的团队
Eliot	因果链日志	原生（动作树）	中	依负载验证	需要追踪复杂因果关系的系统
Logbook	现代化替代	一般	中	依负载验证	需核查版本与集成适配的项目
Picologging	性能优先	需借助 formatter	中（需核对 API 兼容范围）	依负载验证	高吞吐、对性能敏感的服务

1. 标准库 logging：先接住已有依赖的记录

Django、Flask、FastAPI、Celery 等常用框架和依赖能够接入标准库 logging。Logger 产生记录，Handler 选择目的地，Formatter 渲染格式，Filter 负责过滤或调整；应用可以通过 dictConfig 在启动时集中配置。

默认格式不是 JSON，可以使用 python-json-logger 等 Formatter。调用时分开传入参数采用 % 占位符，这与记录最终怎样渲染是两层设置。已有依赖都在使用 logging 时，统一配置和 JSON 输出通常比更换 API 更有价值。

2. Loguru：把输出配置集中到 sink

Loguru 的口号是"让日志变得愉快"——主要围绕一个 logger 对象配置 sink，轮转、序列化等选项可在 add() 中设置：

from loguru import logger

logger.remove()  # 移除默认 stderr sink，避免同时保留一份未配置输出
logger.add("logs/app.log", rotation="100 MB", retention="30 days",
           compression="zip", serialize=True, level="INFO", diagnose=False)

logger.info("用户 {user} 下单 {order}", user="张三", order="A-1024")

轮转、保留、压缩和 JSON 序列化都由 sink 选项控制，消息使用大括号占位符。bind() 和 contextualize() 提供上下文字段；@logger.catch 可以捕获并记录异常，但使用时还要理解异常是否继续传播。示例关闭了 diagnose，避免异常输出泄露局部变量。

第三方库仍可能通过标准 logging 写日志，不会自动进入 Loguru。要共用 sink，需要 InterceptHandler 桥接，并核对级别、异常和调用位置。是否值得换用 Loguru，取决于减少的配置工作能否抵消这层集成维护，不能只按项目大小判断。

3. Structlog：让事件先成为字典

Structlog 可独立使用，也可与标准库组合；它通过处理器链：每条日志经过一串处理器逐步加工（加时间戳、加级别、注入上下文、渲染 JSON）：

import structlog

structlog.configure(
    processors=[
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.processors.add_log_level,
        structlog.processors.JSONRenderer(ensure_ascii=False),
    ],
)
log = structlog.get_logger()
log.info("订单支付成功", order_id="A-1024", amount=99.00)

bind() 返回的 logger 会在后续事件中保留绑定字段，处理器可以补充时间、级别和上下文，dict_tracebacks 用于结构化异常。与标准 logging 组合时，可以让后者分发、structlog 渲染，但渲染责任必须明确，不能让 JSON 再被编码进另一层 JSON message。

团队需要学习处理器和上下文模型；跨服务共用字段规范时，这项投入更容易回收，只需要几条诊断输出的短脚本未必需要它。

4. Eliot：为因果链而生的日志

Eliot 的理念独特：日志不是孤立的行，而是有始有终的动作（action），动作可以嵌套，形成因果树：

from eliot import start_action

with start_action(action_type="process_order", order_id="A-1024"):
    validate()  # 业务函数，由应用实现
    charge()    # 业务函数，由应用实现

还需配置 Eliot 输出目标；已记录的 action 会携带 task UUID、action 层级，事后可还原已埋点操作的调用树，未记录的步骤不会自动补齐。

动作树能提供结构化的执行历史，代价是为关心的步骤显式添加 action。输出和处理方式仍影响性能，相关集成也要由团队维护。若目标是跨服务追踪，应与现有 APM 加 trace_id 日志关联的工作量比较；单个任务的动作树并不自动成为完整分布式链路。

5. Logbook：handler 栈与既有应用

Logbook 是标准库 logging 的替代 API，采用 handler 栈模型；官方文档列出 Armin Ronacher 与 Georg Brandl 等贡献者。

handler 栈适合需要按作用范围切换处理方式的应用。已有 Logbook 系统不必因为另一套 API 更常见就迁移；新项目则需要比较这种模型与标准库依赖之间的集成成本。维护状态、Python 兼容性和所需 handler 应按当前记录核对，不能用“老项目”一词代替判断。

6. Picologging：标准库 API 的性能强化版

Picologging 用 C 扩展重写了标准库 logging 的核心路径，目标是兼容常见标准库 API，但不是完整覆盖，性能收益需按目标调用路径和输出方式测量：

import picologging as logging  # 仅影响此模块别名，不会替换第三方库内部的stdlib logging

logger = logging.getLogger(__name__)
logger.info("hello")

调用点看起来变化很小，Handler、Formatter、第三方集成和配置仍要核对兼容范围。这个片段还需要 handler 和合适级别才能输出 INFO。只有剖析表明日志构造占用了明显 CPU 时，更快的实现才可能解决主要问题；如果瓶颈在磁盘或网络，降低调用开销未必缩短请求时间。

先确定日志要交给谁

常规服务可以从 logging、dictConfig 与 JSON Formatter 开始。Loguru 适合减少 sink 配置工作，structlog 适合把字段与上下文作为团队共同规范；Eliot、Logbook 和 Picologging 则分别解决动作历史、handler 模型与已定位的实现开销。

应用可以使用不同库，采集系统却需要理解同一种契约：时间戳、级别、消息、组件或 logger、服务和关联标识。这些字段一致，跨项目查询与告警才不必随着每个库重新设计。

接入观测云：选型不影响平台侧架构

好消息是：各库可采用相近的文件或stdout采集架构，但字段结构及解析配置并不完全一致：

统一出口：各库都配置为 JSON 输出（标准库用 python-json-logger、Loguru 用 serialize=True、Structlog 用 JSONRenderer），写 stdout（容器）或固定文件（主机）。
统一采集：观测云 DataKit 采集 stdout 或文件，按实际 JSON 结构配置解析，不能假定各库字段路径一致；在 logging.conf 中设置 source（如 python-app）和 service 区分服务。
统一标准化：Pipeline 提取标准 time 与 status 字段，错误日志统一映射为 error 状态，保证跨库的告警规则通用。
统一分析：日志查看器检索与聚类、监控器日志检测告警、多索引成本控制、APM trace_id 关联——全部平台能力与应用选用的日志库解耦。

常见问题（FAQ）

Loguru 项目里第三方库的日志怎么统一？

用 InterceptHandler 把标准库 logging 的记录桥接到 Loguru：logging.basicConfig(handlers=[InterceptHandler()], level=0, force=True)，只有实际传播到这些 handler 的记录才会被桥接；第三方独立 handler、级别及 propagate 设置仍需检查。

Structlog 和标准库 logging 到底什么关系？

Structlog 专注"生成结构化的事件字典"，标准库专注"把记录分发到各 handler"。两者可以组合：Structlog 做渲染、标准库做分发，也可以完全独立使用。大多数团队用 Structlog 全套即可。

团队多个 Python 项目，要不要强制统一日志库？

建议统一"输出契约"而不是统一库：不管什么库，生产环境统一 JSON 格式、统一包含 timestamp/level/logger/message 字段、统一走 stdout 或约定目录。平台侧（观测云）按契约解析，库的选择留给各项目。

异步（asyncio）项目选日志库要注意什么？

标准库 logging 的 Handler 是同步阻塞的，高并发异步服务建议用 QueueHandler + QueueListener 把日志写入放到单独线程，避免阻塞事件循环。Loguru 的 enqueue=True 同理。Picologging 仍需核对 handler 阻塞行为，低日志调用开销不等于异步 I/O。