4. 日志框架选择：Python logging、structlog、loguru 对比，如何输出结构化日志

在构建可观测性体系时，日志框架的选择直接影响结构化日志的输出质量与运维效率。Python 生态中主流的日志框架包括标准库 logging、第三方库 structlog 和 loguru。三者在设计哲学、配置复杂度、性能表现以及结构化支持上存在显著差异。本节将从可观测性实战角度进行系统对比，并给出结构化日志的最佳实践。

4.1 三大框架核心特性对比

4.2 结构化日志输出示例

以下分别展示三种框架输出包含 trace_id 的结构化日志代码。

4.2.1 使用 Python logging 输出结构化日志

import logging
import json
from pythonjsonlogger import jsonlogger

logger = logging.getLogger("my_app")
handler = logging.StreamHandler()
formatter = jsonlogger.JsonFormatter(
    fmt="%(asctime)s %(name)s %(levelname)s %(message)s %(trace_id)s"
)
handler.setFormatter(formatter)
logger.addHandler(handler)
logger.setLevel(logging.INFO)

# 手动注入 trace_id
extra = {"trace_id": "abc123"}
logger.info("用户登录成功", extra=extra)
# 输出: {"asctime": "2025-03-21 10:00:00", "name": "my_app", "levelname": "INFO", "message": "用户登录成功", "trace_id": "abc123"}

4.2.2 使用 structlog 输出结构化日志

import structlog

structlog.configure(
    processors=[
        structlog.stdlib.filter_by_level,
        structlog.stdlib.add_log_level,
        structlog.stdlib.PositionalArgumentsFormatter(),
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.processors.JSONRenderer()
    ],
    wrapper_class=structlog.stdlib.BoundLogger,
    context_class=dict,
    logger_factory=structlog.stdlib.LoggerFactory(),
    cache_logger_on_first_use=True,
)

logger = structlog.get_logger()
# 绑定 trace_id 上下文
logger = logger.bind(trace_id="abc123")
logger.info("用户登录成功", user_id=42)
# 输出: {"event": "用户登录成功", "level": "info", "timestamp": "2025-03-21T10:00:00", "trace_id": "abc123", "user_id": 42}

4.2.3 使用 loguru 输出结构化日志

from loguru import logger
import sys

# 配置 JSON 序列化
logger.remove()
logger.add(
    sys.stdout,
    format="{time:YYYY-MM-DD HH:mm:ss} | {level} | {message} | {extra}",
    serialize=True
)

# 绑定 trace_id
logger = logger.bind(trace_id="abc123")
logger.info("用户登录成功", user_id=42)
# 输出: {"text": "...", "record": {"time": "2025-03-21 10:00:00", "level": "INFO", "message": "用户登录成功", "extra": {"trace_id": "abc123", "user_id": 42}}}

4.3 结构化日志与 OpenTelemetry 链路 ID 关联架构

下图展示了三种日志框架在 OpenTelemetry 链路追踪体系中的位置与数据流关系：

4.4 框架选择决策树

根据项目实际情况，可参考以下决策流程：

1. 是否已有大量 logging 代码？ → 是：保留 logging，通过自定义 Formatter 输出 JSON；否：继续下一步。
2. 是否需要与 OpenTelemetry 深度集成？ → 是：选择 structlog，其处理器链可自动从当前 Span 提取 trace_id；否：继续下一步。
3. 团队是否追求极简配置？ → 是：选择 loguru，一行代码即可启动结构化日志；否：选择 structlog 获得最佳灵活性。

4.5 性能基准参考