📚 课程目录第4章 Go中Trace的生成与传播

4. Go中Trace的生成与传播：使用OpenTelemetry Go SDK创建Tracer、生成Span、注入上下文

在分布式系统性能调优中，Trace（追踪）是定位慢查询的核心手段。OpenTelemetry 作为业界标准的可观测性框架，提供了统一的 API 来生成、传播和导出 Trace 数据。本章将深入讲解如何使用 OpenTelemetry Go SDK 创建 Tracer、生成 Span，并通过上下文传播机制将 Trace 信息跨进程、跨服务传递。

4.1 OpenTelemetry Trace 核心概念

在开始编码之前，需要理解三个核心抽象：Tracer、Span 和 Context。它们之间的关系如下表所示：

概念	职责	生命周期
Tracer	负责创建 Span，通常每个服务/库拥有一个 Tracer 实例	进程级，全局单例
Span	表示一次操作（如数据库查询、RPC 调用），包含名称、开始/结束时间、属性、事件	请求级，从创建到结束
Context	携带 Trace ID、Span ID 等元数据，用于跨协程/跨服务传播	请求级，随调用链传递

最佳实践：每个 Go 包（package）应使用独立的 Tracer 实例，命名规则为 module_name/package_name，便于在 Trace 后端快速定位代码来源。

4.2 创建 Tracer 与生成 Span

以下代码演示了如何初始化 OpenTelemetry SDK、创建 Tracer，并在一个函数中生成根 Span 和子 Span：

package main

import (
    "context"
    "log"
    "time"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/attribute"
    "go.opentelemetry.io/otel/exporters/stdout/stdouttrace"
    "go.opentelemetry.io/otel/sdk/resource"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    semconv "go.opentelemetry.io/otel/semconv/v1.21.0"
    "go.opentelemetry.io/otel/trace"
)

// 初始化 Trace Provider
func initTracer() (*sdktrace.TracerProvider, error) {
    exporter, err := stdouttrace.New(stdouttrace.WithPrettyPrint())
    if err != nil {
        return nil, err
    }
    tp := sdktrace.NewTracerProvider(
        sdktrace.WithBatcher(exporter),
        sdktrace.WithResource(resource.NewWithAttributes(
            semconv.SchemaURL,
            semconv.ServiceNameKey.String("order-service"),
            semconv.ServiceVersionKey.String("1.0.0"),
        )),
    )
    otel.SetTracerProvider(tp)
    return tp, nil
}

func main() {
    tp, err := initTracer()
    if err != nil {
        log.Fatal(err)
    }
    defer tp.Shutdown(context.Background())

    // 获取 Tracer
    tracer := otel.Tracer("order-service/db")

    // 创建根 Span
    ctx, span := tracer.Start(context.Background(), "processOrder",
        trace.WithAttributes(
            attribute.String("order.id", "ORD-12345"),
            attribute.Int("item.count", 3),
        ),
    )
    defer span.End()

    // 模拟业务逻辑：查询数据库
    queryDatabase(ctx, tracer)

    time.Sleep(100 * time.Millisecond) // 模拟处理时间
}

func queryDatabase(ctx context.Context, tracer trace.Tracer) {
    // 创建子 Span，自动继承父 Span 的 Trace ID
    _, childSpan := tracer.Start(ctx, "db.query",
        trace.WithAttributes(
            attribute.String("db.system", "postgresql"),
            attribute.String("db.statement", "SELECT * FROM orders WHERE id = ?"),
        ),
    )
    defer childSpan.End()

    // 模拟慢查询
    time.Sleep(200 * time.Millisecond)
    childSpan.AddEvent("query.completed",
        trace.WithAttributes(attribute.Int("rows.returned", 42)),
    )
}

  关键点：
  otel.Tracer(name) 返回一个命名 Tracer，name 通常使用 服务名/模块名 格式。
tracer.Start(ctx, spanName) 返回新的 Context 和 Span。传入的 ctx 如果包含父 Span，则自动建立父子关系。
span.AddEvent() 用于记录时间戳事件，适合标记慢查询中的关键阶段。

4.3 Span 的层级结构与传播机制

Trace 的传播依赖于 Go 的 context.Context。OpenTelemetry 将 Span 元数据（Trace ID、Span ID、采样标记等）编码到 Context 中，通过函数参数传递实现跨协程传播。下图展示了在一次慢查询请求中，Span 的层级结构与传播路径：

4.4 跨服务传播：W3C Trace Context 协议

在微服务架构中，Trace 需要跨越进程边界。OpenTelemetry 默认使用 W3C Trace Context 标准，通过 HTTP 头 traceparent 和 tracestate 传递 Trace 元数据。下表对比了两种常见的传播方式：

传播方式	协议	传播载体	适用场景
HTTP 传播	W3C Trace Context	HTTP 请求头（traceparent）	REST API、Web 服务
gRPC 传播	gRPC Metadata	gRPC 上下文元数据	内部微服务 RPC 调用

以下代码展示了如何在 HTTP 客户端和服务端之间传播 Trace：

// 客户端：注入 Trace 上下文到 HTTP 请求
func callDownstream(ctx context.Context, url string) error {
    req, _ := http.NewRequestWithContext(ctx, "GET", url, nil)
    // 使用 OpenTelemetry 的 HTTP 传播器注入 traceparent 头
    otel.GetTextMapPropagator().Inject(ctx, propagation.HeaderCarrier(req.Header))
    _, err := http.DefaultClient.Do(req)
    return err
}

// 服务端：从 HTTP 请求提取 Trace 上下文
func handler(w http.ResponseWriter, r *http.Request) {
    // 从请求头中提取 Trace 上下文
    ctx := otel.GetTextMapPropagator().Extract(r.Context(), propagation.HeaderCarrier(r.Header))
    tracer := otel.Tracer("order-service/http")
    _, span := tracer.Start(ctx, "handle.request")
    defer span.End()
    // ... 处理请求
}

常见陷阱：忘记在 http.NewRequestWithContext 中传入携带 Trace 的 Context，会导致下游服务无法关联父 Span，形成断链。始终确保 ctx 包含有效的 Span 元数据。

4.5 慢查询场景的 Trace 属性与事件

在慢查询调优中，Span 的属性和事件是定位瓶颈的关键。推荐为每个数据库 Span 添加以下属性：

db.system：数据库类型（postgresql、mysql、redis）
db.statement：SQL 语句或命令（注意脱敏）
db.operation：操作类型（SELECT、INSERT、QUERY）
db.instance：数据库实例名称
net.peer.name：数据库主机地址

同时，使用 Span 事件 记录慢查询的关键时间点：

// 在慢查询 Span 中添加事件
span.AddEvent("query.start",
    trace.WithAttributes(attribute.String("query.plan", "seq_scan")))
// ... 执行查询
span.AddEvent("query.completed",
    trace.WithAttributes(
        attribute.Int64("duration_ms", 230),
        attribute.Int("rows.scanned", 100000),
    ))

  调优技巧：当查询耗时超过阈值（如 100ms）时，自动在 Span 上添加 slow_query: true 属性，并在事件中记录执行计划。这样在 Trace 后端可以快速过滤出所有慢查询 Span。

4.6 完整 Trace 链路示例

下图展示了一个包含 HTTP 入口、数据库慢查询、缓存查询的完整 Trace 链路，以及各 Span 之间的父子关系：

4.7 本章小结

Tracer 是 Span 的工厂，每个模块应使用独立的命名 Tracer。
Span 通过 tracer.Start(ctx, name) 创建，父子关系由 Context 自动维护。
Context 传播 是 Trace 链路的基石，跨协程传递 ctx，跨服务使用 W3C Trace Context 协议。
在慢查询 Span 中添加属性和事件，为后续性能分析提供关键数据。