OpenTelemetry 是 Go 微服务链路追踪首选，因 Go 生态已弃用 opentracing/opencensus；需用 go.opentelemetry.io/otel，手动注入 otelhttp/otelgrpc 拦截器，跨 goroutine 用 propagator 注入 context，采样率生产环境须设为 0.01。
为什么 OpenTelemetry 是当前 Go 微服务链路追踪的首选
Go 生态中已基本放弃维护 opentracing 和 opencensus，OpenTelemetry（OTel）是官方合并后的统一标准。直接用 go.opentelemetry.io/otel 而非旧包，否则会遇到 undefined: otel.Tracer 或 context 透传失败等问题。
- Go SDK 默认不自动采集 HTTP/gRPC 入口，需手动注入
otelhttp.NewHandler或otelgrpc.UnaryServerInterceptor - 跨 goroutine 传递 trace context 必须用
context.WithValue+otel.GetTextMapPropagator().Inject，仅靠原始context.Background()会导致断链 - 采样率默认为
TraceIDRatioBased(1.0)（全量），生产环境务必设为TraceIDRatioBased(0.01)避免压垮后端 collector
如何在 Gin 中注入 HTTP 入口追踪
Gin 默认中间件不兼容 OTel 的 context 传播机制，必须用 otelhttp.NewHandler 包裹 handler，而非简单调用 span := tracer.Start(ctx, ...)。
import (
"go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin"
"go.opentelemetry.io/otel"
)
r := gin.Default()
r.Use(otelgin.Middleware("my-api")) // 自动处理入参、状态码、延迟
r.GET("/user/:id", func(c *gin.Context) {
id := c.Param("id")
ctx := c.Request.Context() // 已含 trace context
tracer := otel.Tracer("user-handler")
_, span := tracer.Start(ctx, "fetch-user")
defer span.End()
// 下游调用需显式传 ctx，例如：
resp, _ := http.DefaultClient.Do(http.NewRequestWithContext(ctx, "GET", "http://svc-user/profile/"+id, nil))
})
- 忘记在
http.NewRequest中使用WithContext(ctx, ...)→ 下游服务收不到 traceparent header → 链路断裂 -
otelgin.Middleware会自动记录http.status_code、http.method，但不会记录业务字段（如 user_id），需手动span.SetAttributes(attribute.String("user.id", id)) - 若用自定义 router（如 chi），需改用
otelchi.Middleware，API 行为不一致
gRPC 客户端和服务端如何保持 trace 上下文
gRPC 的 metadata 透传需配合 otelgrpc 拦截器，否则即使服务端启用 OTel，也无法关联客户端 span。
// 客户端
conn, _ := grpc.Dial("localhost:8080",
grpc.WithTransportCredentials(insecure.NewCredentials()),
grpc.WithUnaryInterceptor(otelgrpc.UnaryClientInterceptor()),
)
client := pb.NewUserServiceClient(conn)
ctx := context.Background()
// 必须用 ExtractFromCarrier 或直接传带 trace 的 ctx
ctx = otel.GetTextMapPropagator().Extract(ctx, propagation.HeaderCarrier(req.Header))
_, _ = client.GetUser(ctx, &pb.GetUserRequest{Id: "123"})
// 服务端
s := grpc.NewServer(
grpc.UnaryInterceptor(otelgrpc.UnaryServerInterceptor()),
)
pb.RegisterUserServiceServer(s, &userServer{})
- 客户端未启用
UnaryClientInterceptor→ 服务端收到的ctx无 span → 所有子 span 变成 root span - gRPC 流式接口（Streaming）需额外配置
StreamClientInterceptor和StreamServerInterceptor，否则流内多次消息不共享同一 trace - 若服务间通过消息队列（如 Kafka）通信，需手动在 message headers 中注入
traceparent，OTel 不自动支持
本地开发时如何快速验证 trace 是否连通
不用搭 Jaeger 或 Tempo，用 otlphttp 导出到本地 otel-collector 并启用 logging exporter 最省事。
立即学习“go语言免费学习笔记（深入）”；
import (
"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
"go.opentelemetry.io/otel/sdk/trace"
)
exp, _ := otlptracehttp.New(context.Background(),
otlptracehttp.WithEndpoint("localhost:4318"),
otlptracehttp.WithInsecure(), // 开发时跳过 TLS
)
tp := trace.NewTracerProvider(
trace.WithBatcher(exp),
trace.WithSampler(trace.AlwaysSample()), // 临时全采
)
otel.SetTracerProvider(tp)
- 忘记调用
otel.SetTracerProvider(tp)→ 所有otel.Tracer(...).Start返回空 span → 日志里全是 “no span found” - collector 配置中未启用
loggingexporter，或未设置exporters: [logging]→ 看不到原始 trace 数据结构 -
浏览器访问服务时，Chrome DevTools Network 标签页能看到
traceparentheader，这是最直接的链路存在证据
真正难的不是埋点，而是确保每个 goroutine、每次 HTTP/gRPC 调用、每条 MQ 消息都携带且正确解析了 traceparent。少一处 context 透传，整条链就断在那个节点。
