context.Context 是日志追踪的起点，因 Go 无隐式 TLS，需显式透传 traceID；所有中间件、HTTP handler、RPC 和 DB 操作都应从 ctx 获取而非生成新 ID，避免污染业务逻辑。
为什么 context.Context 是日志追踪的起点
Go 没有隐式线程局部存储（TLS），跨 goroutine 传递追踪 ID 必须显式透传。不靠 context.Context，就只能在每个函数签名里硬加一个 traceID string 参数——这会污染业务逻辑，且极易漏传。所有中间件、HTTP handler、RPC 调用、数据库操作，都该从 ctx 里取 traceID，而不是生成新的。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- HTTP 入口统一从请求头（如
X-Trace-ID）提取，若不存在则生成新 ID，并写入context.WithValue(ctx, keyTraceID, id) - 下游调用时，把当前
ctx中的traceID注入到 HTTP header 或 gRPC metadata 中 - 避免用
context.WithValue存任意结构体；只存字符串 ID，否则难以序列化和透传 - 日志库（如
zap）需配置zap.AddCaller()和自定义zap.Field注入traceID，而非每次logger.Info("msg", zap.String("trace_id", id))
gRPC 和 HTTP 之间如何保持 traceID 不断链
混合架构下，HTTP 服务调用 gRPC 微服务，或反之，traceID 极易丢失。gRPC 默认不解析 HTTP header，而 HTTP client 也不会自动读取 gRPC metadata。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- HTTP server 端：用
middleware提取X-Trace-ID，塞进context；再通过grpc.WithUnaryInterceptor在 client 端将ctx.Value(keyTraceID)写入metadata.MD{"trace-id": []string{id}} - gRPC server 端：用
grpc.UnaryServerInterceptor从metadata.FromIncomingContext(ctx)读取trace-id，写回context - 注意大小写：gRPC metadata key 会自动转为小写，
trace-id比Trace-ID更可靠 - 不要依赖
req.Header.Get("X-Trace-ID")在 gRPC handler 里手动取——它根本不在 gRPC 请求里
opentelemetry-go 的最小可行集成方式
直接上 jaeger 或 zipkin SDK 容易卡在采样率、exporter 配置、span 生命周期等细节里。OpenTelemetry 是当前最稳的抽象层，但不必全量引入。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 只导入核心包：
go.opentelemetry.io/otel、go.opentelemetry.io/otel/sdk/trace、go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp - 初始化 tracer provider 时，设置
WithSampler(oteltrace.AlwaysSample())用于调试，上线后改用oteltrace.ParentBased(oteltrace.TraceIDRatioBased(0.01)) - HTTP handler 中用
otel.Tracer("http").Start(ctx, "handler")，别忘了defer span.End() - gRPC server interceptor 中调用
span := trace.SpanFromContext(ctx)获取父 span，再用tracer.Start(spanCtx, "rpc-call")创建子 span - exporter 失败默认静默，加
WithSyncer()并监听err != nil才能发现配置错误
日志字段与 traceID 对齐时最容易被忽略的坑
即使 traceID 正确透传，日志仍可能无法关联到调用链——因为日志字段名和 APM 后端期望不一致，或 span 中未记录关键事件。
常见错误现象：
- Jaeger UI 显示 span，但点开后看不到任何日志条目 → 日志没打到 span 上，或字段名不是
event/message - 同一 traceID 在不同服务日志中出现，但时间戳乱序 → 没启用纳秒级时间戳，或系统时钟未 NTP 同步
- HTTP 400 错误没出现在 span 的
status.code中 → 忘了调用span.SetStatus(codes.Error, "bad request") - 数据库慢查询没标记为 error →
span.RecordError(err)必须显式调用，不会自动捕获
关键点：traceID 只是索引，真正让日志可追溯的是结构化字段 + 时间精度 + 状态标记。别只盯着 ID 传没传对。
