📚 课程目录第3章日志采集架构

3. 日志采集架构：结构化日志、日志级别、日志上下文、分布式追踪ID（Trace ID）的设计

在异步任务编排场景中，日志不再是简单的文本输出，而是需要支撑快速检索、关联分析和全链路追踪的工程化数据。本节围绕四个核心设计要素展开：结构化日志、日志级别、日志上下文以及分布式追踪ID（Trace ID）。

3.1 结构化日志：从文本到可解析数据

传统文本日志（如 User 123 login failed）难以被机器解析和聚合。结构化日志将每条日志记录为键值对（Key-Value）或JSON格式，使日志系统能够直接提取字段进行过滤、统计和告警。

对比维度	文本日志	结构化日志
可读性	人类直接阅读	需格式化输出，但机器友好
检索效率	依赖正则匹配，性能低	按字段索引，毫秒级查询
字段扩展	追加文本，解析困难	新增键值对，向后兼容
典型格式	`2025-03-21 10:00:00 ERROR timeout`	`{"time":"...","level":"ERROR","msg":"timeout","duration":5000}`

  实践建议：在Python中使用structlog或python-json-logger库，将日志处理器配置为JSON格式输出。避免在异步回调中手动拼接字符串，始终使用结构化绑定字段。

3.2 日志级别：控制信息密度与告警阈值

异步任务编排中，同一任务可能产生大量日志。合理的日志级别设计能帮助开发者在开发环境快速定位问题，同时在生产环境避免日志洪流。标准级别及在异步场景下的使用建议如下：

DEBUG：记录任务编排的每一步决策、队列状态变化、中间变量值。仅在开发环境开启。
INFO：记录任务开始、结束、重试次数、关键业务状态变更。作为默认输出级别。
WARNING：记录非致命异常，如任务执行超时（但仍在重试阈值内）、资源竞争、降级策略触发。
ERROR：记录任务执行失败、数据一致性破坏、外部服务不可用等需要人工介入的事件。
CRITICAL：记录系统级故障，如消息队列不可用、数据库连接池耗尽、编排引擎崩溃。

避坑提示：不要在异步回调中动态修改日志级别。应在任务初始化时根据上下文（如是否为开发环境）确定全局级别，避免因并发修改导致日志丢失或级别混乱。

3.3 日志上下文：绑定任务维度的附加信息

在异步任务中，单条日志往往无法完整描述问题。日志上下文（Log Context）允许开发者将任务ID、用户ID、请求来源、任务类型等维度信息自动注入到每条日志中，无需在每个日志调用处手动传递。

实现方式通常使用线程局部存储（ThreadLocal）或协程上下文（ContextVar）。在Python异步框架（如Celery、FastAPI + asyncio）中，推荐使用contextvars模块：

import contextvars
import logging

# 定义上下文变量
task_context = contextvars.ContextVar('task_context', default={})

class ContextInjector(logging.Filter):
    def filter(self, record):
        ctx = task_context.get()
        for key, value in ctx.items():
            setattr(record, key, value)
        return True

# 在任务开始时设置上下文
async def process_task(task_id, user_id):
    ctx = {'task_id': task_id, 'user_id': user_id}
    token = task_context.set(ctx)
    try:
        logger.info("开始处理任务")
        # ... 业务逻辑
    finally:
        task_context.reset(token)

注意：使用contextvars时，务必在任务结束时调用reset()，否则上下文会泄漏到后续的协程或线程中，导致日志字段错乱。

3.4 分布式追踪ID（Trace ID）：串联跨服务调用链

在微服务架构中，一个异步任务可能跨越多个服务（如任务编排服务 → 计算服务 → 存储服务）。Trace ID 作为全局唯一标识，贯穿整个调用链，使开发者能够从入口到出口完整还原一次请求的路径。

Trace ID 的设计原则：

全局唯一：通常使用 UUID、Snowflake ID 或结合时间戳+机器ID+序列号的组合。
透传透明：在服务间调用（HTTP、gRPC、消息队列）时，自动注入到请求头或消息属性中。
父子关系：每个子任务生成唯一的 Span ID，并记录父 Span ID，形成树形结构。

3.5 架构整合：结构化日志 + 上下文 + Trace ID

将上述三个要素整合到日志采集架构中，形成统一的日志记录规范。以下是一个典型的日志记录示例（JSON 格式）：

{
  "timestamp": "2025-03-21T10:00:00.123Z",
  "level": "ERROR",
  "logger": "task_executor",
  "message": "任务执行超时，触发重试",
  "trace_id": "T-001",
  "span_id": "B-003",
  "parent_span_id": "A-001",
  "task_id": "task-789",
  "user_id": "user-456",
  "task_type": "data_sync",
  "retry_count": 2,
  "duration_ms": 12000,
  "exception": "TimeoutError: Connection refused"
}

  架构要点：
  强制字段：trace_id、span_id、task_id 必须由框架自动注入，不允许业务代码手动赋值。
可选字段：user_id、task_type 等业务维度信息，通过日志上下文自动绑定。
异常字段：exception 字段仅在 ERROR/CRITICAL 级别出现，避免日志体积膨胀。

3.6 开发环境下的落地检查清单

在开发环境验证日志采集架构时，建议逐项确认以下要点：

结构化输出：所有日志是否已切换为 JSON 格式？是否包含 timestamp、level、logger、message 四个基础字段？
级别覆盖：是否在关键路径（任务开始、结束、异常、重试）使用了正确的日志级别？DEBUG 日志是否仅在开发环境生效？
上下文完整性：每条日志是否自动携带了 task_id 和 trace_id？在异步回调中上下文是否丢失？
Trace ID 透传：当任务通过消息队列或 HTTP 调用下游服务时，Trace ID 是否被正确传递？下游日志是否包含相同的 Trace ID？
检索验证：在日志聚合系统中按 Trace ID 搜索，是否能返回该请求的全链路日志？日志时间戳是否按顺序排列？

快速验证方法：在开发环境启动一个包含 3 个异步子任务的编排流程，故意在其中一个子任务中抛出异常。然后按 Trace ID 检索日志，检查是否能完整看到入口请求、编排决策、子任务执行、异常堆栈以及重试记录。如果任何一段日志缺失，说明上下文或 Trace ID 透传存在断点。