链路追踪（TraceID）

说明

链路追踪通过为每个请求分配唯一的 TraceID，将同一请求的所有日志串联起来，方便问题排查和性能分析。TraceID 在请求进入时生成，注入响应头，并通过 contextvars 传递到整个请求链路。

工作原理

请求进入
   │
   ├─ 生成 TraceID（UUID4 短格式）
   ├─ 注入到 response header: X-Trace-Id
   ├─ 存入 contextvar: current_trace_id
   │
   ├─ Handler 处理请求
   │   └─ Service → Repository → DB
   │       └─ 日志中自动携带 TraceID
   │
   └─ 响应返回（携带 X-Trace-Id 头）

实现

中间件层

# src/common/middleware/trace_id.py
import uuid
from core.context import current_trace_id

def apply_trace_id(handler):
    """为请求生成 TraceID 并注入响应头。"""
    trace_id = uuid.uuid4().hex[:16]
    current_trace_id.set(trace_id)
    handler.set_header("X-Trace-Id", trace_id)

上下文变量

# src/core/context.py
import contextvars

current_trace_id: contextvars.ContextVar[str] = contextvars.ContextVar(
    "current_trace_id", default=""
)
current_user_id: contextvars.ContextVar[int] = contextvars.ContextVar(
    "current_user_id", default=0
)
current_username: contextvars.ContextVar[str] = contextvars.ContextVar(
    "current_username", default=""
)
current_realname: contextvars.ContextVar[str] = contextvars.ContextVar(
    "current_realname", default=""
)

在 BaseHandler 中调用

# src/core/base_handler.py
class BaseHandler(tornado.web.RequestHandler):
    def set_default_headers(self):
        super().set_default_headers()
        cros_required(self)
        apply_trace_id(self)  # 注入 TraceID

日志中的 TraceID

JSON 结构化日志自动携带 TraceID：

# src/core/logger.py
# 日志格式中包含 trace_id 字段
{
    "timestamp": "2024-01-15T10:30:00",
    "level": "INFO",
    "trace_id": "a1b2c3d4e5f6g7h8",
    "user_id": 1,
    "message": "操作日志记录"
}

使用场景

场景	说明
问题排查	通过 TraceID 搜索同一请求的所有日志
性能分析	追踪请求在各层的耗时
异常定位	异常日志携带 TraceID，快速定位上下文
用户反馈	用户报告问题时提供 TraceID，精确定位

响应头

每个 API 响应都携带 X-Trace-Id 头：

HTTP/1.1 200 OK
X-Trace-Id: a1b2c3d4e5f6g7h8
Content-Type: application/json

{"code": 0, "data": {...}, "msg": "操作成功", "ok": true}

总结

链路追踪方案具备以下特点：

1. 自动生成：每个请求进入时生成唯一 TraceID（UUID4 短格式）
2. 上下文传递：通过 contextvars 传递到整个请求链路
3. 响应注入：X-Trace-Id 响应头，前端可记录
4. 日志关联：JSON 结构化日志自动携带 TraceID
5. 零侵入：业务代码无需感知，自动生效