1. 分布式追踪基础

1.1 什么是分布式追踪

分布式追踪（Distributed Tracing）是一种用于监控和诊断微服务架构中请求全链路行为的可观测性技术。它通过为每个请求分配唯一的 Trace ID，并在服务间传播，将一次业务请求经过的所有服务节点、调用耗时、状态信息串联起来，形成一条完整的调用链路。

1.2 分布式追踪的核心价值

1.3 分布式追踪 vs 单体追踪

单体架构下，追踪通常依赖日志关键字或简单的请求 ID 关联，所有调用都在同一进程内完成，上下文天然共享。微服务架构下，请求跨进程、跨网络、跨语言，传统日志聚合方式无法还原完整调用链。

1.4 分布式追踪核心概念

• Trace（追踪）：一次完整业务请求的端到端链路，由多个 Span 组成树形结构。
• Span（跨度）：Trace 中的最小工作单元，记录一个操作（如一次 RPC 调用、一次数据库查询）的开始时间、结束时间、状态和元数据。
• Span Context（跨度上下文）：包含 Trace ID、Span ID、Baggage 等，用于跨进程传递追踪状态。
• Parent-Child 关系：Span 之间的父子层级，构成 Trace 的树形拓扑。

1.5 分布式追踪的典型数据模型

一个完整的 Trace 数据通常包含以下字段，以 JSON 格式存储于追踪后端：

{
  "traceId": "abc123def456",
  "spans": [
    {
      "spanId": "span-1",
      "parentSpanId": null,
      "operationName": "POST /api/order",
      "startTime": 1710000000000000,
      "endTime":   1710000000123000,
      "durationMs": 123,
      "status": "OK",
      "serviceName": "api-gateway",
      "tags": {
        "http.method": "POST",
        "http.status_code": 200
      }
    },
    {
      "spanId": "span-2",
      "parentSpanId": "span-1",
      "operationName": "createOrder",
      "startTime": 1710000000010000,
      "endTime":   1710000000110000,
      "durationMs": 100,
      "status": "OK",
      "serviceName": "order-service",
      "tags": {
        "db.type": "mysql",
        "db.statement": "INSERT INTO orders ..."
      }
    }
  ]
}

1.6 分布式追踪的典型工作流程

1. 注入：请求入口处生成 Trace ID，并注入到请求上下文（如 HTTP Header x-trace-id）。
2. 传播：Trace ID 和 Span Context 随请求在服务间传递，每个服务创建新的 Span 并记录父子关系。
3. 采集：各服务将 Span 数据异步发送到追踪 Collector（如 Jaeger Agent、OpenTelemetry Collector）。
4. 存储：Collector 将 Span 写入后端存储（如 Elasticsearch、Cassandra、ClickHouse）。
5. 查询：通过追踪 UI 按 Trace ID、服务名、标签、时间范围检索链路。
6. 分析：查看火焰图、服务拓扑、耗时分布，定位瓶颈或错误。

1.7 平台工程视角：为什么需要自助查询接口

在平台工程实践中，分布式追踪不仅是 SRE 的排障工具，更应成为所有研发团队的自助能力。传统模式下，开发者需要向 SRE 申请 Trace ID 查询权限或依赖 Grafana 等复杂 UI，效率低下。平台工程的目标是提供 自助查询接口，让开发者通过简单的 API 或 CLI 即可按 Trace ID、服务名、标签、时间范围检索链路，并直接嵌入到 CI/CD 流水线、告警通知和日常排障流程中。