4. 头部采样实战：基于 Jaeger 的头部采样配置与代码示例

头部采样（Head-Based Sampling）在 Trace 入口处根据预设规则决定是否采样整条链路，具有低延迟、实现简单的特点。本节以 Jaeger 为例，讲解头部采样的配置方法、代码集成与生产级注意事项。

4.1 头部采样核心原理

头部采样在 Span 创建之初（通常是入口服务或网关层）读取采样决策，并将该决策通过 Propagation 机制传递给下游服务。所有子 Span 继承父 Span 的采样标记，无需重复判断。

4.2 Jaeger 头部采样配置方式

Jaeger 支持三种头部采样策略，通过环境变量或配置文件设定：

4.3 代码示例：Go 语言集成 Jaeger 头部采样

以下示例展示如何在 Go 微服务中配置 Jaeger 头部采样，并确保采样决策正确传播：

package main

import (
    "io"
    "log"
    "net/http"
    "os"
    "time"

    "github.com/opentracing/opentracing-go"
    "github.com/uber/jaeger-client-go"
    "github.com/uber/jaeger-client-go/config"
)

// initJaeger 初始化 Jaeger Tracer，配置头部采样
func initJaeger(serviceName string) (opentracing.Tracer, io.Closer) {
    // 从环境变量读取采样配置
    samplerType := os.Getenv("JAEGER_SAMPLER_TYPE")
    if samplerType == "" {
        samplerType = "probabilistic" // 默认概率采样
    }
    samplerParam := 0.1 // 默认 10% 采样率

    cfg := &config.Configuration{
        ServiceName: serviceName,
        Sampler: &config.SamplerConfig{
            Type:  samplerType,
            Param: samplerParam,
        },
        Reporter: &config.ReporterConfig{
            LogSpans:            false,
            BufferFlushInterval: 1 * time.Second,
            LocalAgentHostPort:  "jaeger-agent:6831",
        },
    }

    tracer, closer, err := cfg.NewTracer(
        config.Logger(jaeger.StdLogger),
    )
    if err != nil {
        log.Fatalf("无法初始化 Jaeger tracer: %v", err)
    }
    return tracer, closer
}

// 入口服务 HTTP Handler
func entryHandler(w http.ResponseWriter, r *http.Request) {
    tracer := opentracing.GlobalTracer()
    // 从请求中提取父 SpanContext（如果有）
    spanCtx, _ := tracer.Extract(
        opentracing.HTTPHeaders,
        opentracing.HTTPHeadersCarrier(r.Header),
    )
    // 创建入口 Span，采样决策在此处做出
    span := tracer.StartSpan("entry-service", 
        opentracing.ChildOf(spanCtx),
    )
    defer span.Finish()

    // 调用下游服务，传递采样标记
    downstreamURL := "http://middle-service/api"
    req, _ := http.NewRequest("GET", downstreamURL, nil)
    // 将当前 SpanContext 注入到 HTTP 头
    tracer.Inject(span.Context(), 
        opentracing.HTTPHeaders,
        opentracing.HTTPHeadersCarrier(req.Header),
    )
    // 发送请求
    client := &http.Client{Timeout: 5 * time.Second}
    resp, err := client.Do(req)
    if err != nil {
        log.Printf("调用下游服务失败: %v", err)
    } else {
        resp.Body.Close()
    }
}

func main() {
    tracer, closer := initJaeger("entry-service")
    defer closer.Close()
    opentracing.SetGlobalTracer(tracer)

    http.HandleFunc("/api", entryHandler)
    log.Println("入口服务启动在 :8080")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

4.4 采样决策验证与调试

部署后需验证采样决策是否正确传播。推荐以下验证方法：

• Jaeger UI 检查：查看 Trace 详情，确认所有 Span 的 sampled 标记一致。
• 日志输出：开启 JAEGER_REPORTER_LOG_SPANS=true，观察 Span 是否被上报。
• 指标监控：通过 Jaeger 内置指标（如 jaeger_tracer_reporter_spans_total）对比采样前后数量。
• 手动注入测试：使用 curl 添加 uber-trace-id: {trace-id}:0:0:01 头，验证强制采样。

4.5 头部采样 vs 尾部采样对比