Go权限审计网关链路追踪 - 第4节

4.1 分布式追踪的核心问题

在微服务架构中，一个用户请求往往需要经过多个服务节点协同处理。当请求处理变慢或失败时，传统的单体日志和单机监控无法回答以下关键问题：

• 请求到底经过了哪些服务？
• 哪个环节耗时最长？
• 哪个服务抛出了异常？

分布式追踪（Distributed Tracing）通过为每个请求注入全局唯一的追踪标识，并记录其在各服务间的调用链路与耗时，从而完整还原请求的“旅程”。

4.2 OpenTelemetry 标准入门

OpenTelemetry（简称 OTel）是由 CNCF 孵化的可观测性标准，统一了分布式追踪、指标和日志的采集规范。它提供了厂商中立的 API、SDK 和协议，开发者只需接入 OTel，即可将数据导出到 Jaeger、Zipkin、Prometheus、Datadog 等任意后端。

4.2.1 Trace / Span / Context 核心概念

关键关系：

• 一个 Trace 包含一个根 Span（Root Span）和若干子 Span（Child Span）。
• 每个 Span 都包含一个 Trace ID（全局唯一）和一个 Span ID（当前 Span 唯一）。
• Context 通过 Span 的 Parent Span ID 建立父子关系，形成调用链。

4.2.2 W3C Trace Context 协议

W3C Trace Context 是业界标准的 HTTP 追踪上下文传播协议，定义了两种 HTTP Header：

traceparent 字段详解：

• 版本号（00）： 当前协议版本，固定为 00。
• Trace ID（32 位十六进制）： 全局唯一，标识整个 Trace。
• Parent Span ID（16 位十六进制）： 调用方 Span ID，接收方将其作为自己的父 Span。
• Trace Flags（2 位十六进制）： 最低位（01）表示是否采样，01 为采样，00 为不采样。

4.3 OTel Go SDK 安装与初始化

本节将演示如何在 Go 项目中安装 OpenTelemetry SDK，并完成基础初始化配置，为后续在网关中集成链路追踪做好准备。

4.3.1 安装依赖

使用 go get 安装核心 SDK 和标准导出器（以 Jaeger 为例）：

go get go.opentelemetry.io/otel \
       go.opentelemetry.io/otel/sdk \
       go.opentelemetry.io/otel/exporters/jaeger \
       go.opentelemetry.io/otel/trace

依赖说明：

4.3.2 初始化 TracerProvider

以下代码展示了如何在 Go 应用启动时初始化 OTel SDK，配置 Jaeger 导出器和采样策略：

package main

import (
    "context"
    "log"
    "time"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/attribute"
    "go.opentelemetry.io/otel/exporters/jaeger"
    "go.opentelemetry.io/otel/sdk/resource"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    semconv "go.opentelemetry.io/otel/semconv/v1.17.0"
)

// initTracerProvider 初始化全局 TracerProvider
func initTracerProvider() (*sdktrace.TracerProvider, error) {
    // 1. 创建 Jaeger Exporter
    exp, err := jaeger.New(jaeger.WithCollectorEndpoint(
        jaeger.WithEndpoint("http://localhost:14268/api/traces"),
    ))
    if err != nil {
        return nil, err
    }

    // 2. 定义服务资源信息
    res, err := resource.New(context.Background(),
        resource.WithAttributes(
            semconv.ServiceNameKey.String("auth-gateway"),
            attribute.String("environment", "production"),
        ),
    )
    if err != nil {
        return nil, err
    }

    // 3. 创建 TracerProvider
    tp := sdktrace.NewTracerProvider(
        sdktrace.WithBatcher(exp),
        sdktrace.WithResource(res),
        sdktrace.WithSampler(sdktrace.AlwaysSample()), // 生产环境建议使用 ParentBased(0.1)
    )

    // 4. 设置为全局 TracerProvider
    otel.SetTracerProvider(tp)
    return tp, nil
}

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

    // 业务代码...
}

4.3.3 创建第一个 Span

初始化完成后，即可通过全局 TracerProvider 获取 Tracer 并创建 Span：

func handleRequest(ctx context.Context) {
    // 获取 Tracer
    tracer := otel.Tracer("auth-gateway-tracer")

    // 创建 Span
    ctx, span := tracer.Start(ctx, "handleRequest")
    defer span.End()

    // 添加属性
    span.SetAttributes(
        attribute.String("http.method", "POST"),
        attribute.String("http.url", "/api/order/create"),
    )

    // 模拟业务逻辑
    doBusinessLogic(ctx)
}

func doBusinessLogic(ctx context.Context) {
    // 创建子 Span
    _, span := otel.Tracer("auth-gateway-tracer").Start(ctx, "doBusinessLogic")
    defer span.End()

    // 模拟耗时
    time.Sleep(50 * time.Millisecond)
}

4.4 本章小结

• 分布式追踪通过 Trace、Span、Context 三个核心概念还原请求全链路。
• W3C Trace Context 协议定义了 traceparent 和 tracestate 两个 HTTP Header，实现跨服务追踪上下文传播。
• OTel Go SDK 的初始化流程包括：创建 Exporter → 定义 Resource → 构建 TracerProvider → 设置为全局实例。
• 通过 tracer.Start(ctx, name) 创建 Span，并利用 Context 在函数调用链中传递追踪状态。