Go项目接入OpenTelemetry链路追踪的核心是确保TracerProvider全局唯一、Span生命周期由上下文传递、导出器异步非阻塞；需在main入口尽早初始化provider，HTTP服务用otelhttp中间件注入context，客户端调用显式传播trace context，导出器启用异步批处理与重试。
Go 项目接入 OpenTelemetry 链路追踪，核心不是“装一堆包”，而是确保 TracerProvider 全局唯一、Span 生命周期由上下文传递、导出器（Exporter）不阻塞主流程。否则容易出现 Span 丢失、trace_id 不一致、CPU 占用突增等问题。
初始化 TracerProvider 必须在 main 入口尽早完成
OpenTelemetry 的 TracerProvider 是线程安全但不可重建的全局资源。延迟初始化（比如在 handler 里首次调用才创建）会导致不同 goroutine 获取到不同实例，Span 无法关联成完整链路。
常见错误现象：trace_id 在 HTTP 请求中频繁变化、下游服务收不到 parent span context。
- 在
main()函数最开始就调用otlphttp.NewClient()+otlphttp.NewExporter()构建导出器 - 用
sdktrace.NewTracerProvider()创建 provider，并通过otel.SetTracerProvider()注册为全局实例 - 避免在 init() 中初始化 —— 若有多个包 init 顺序不确定，可能被覆盖
- 若使用 Gin/Echo 等框架，不要把 provider 初始化放在中间件里
HTTP Server 自动注入 Span 需要适配标准中间件
OpenTelemetry 官方未提供 Go 的通用 HTTP 中间件，必须手动包装或选用社区验证过的实现（如 go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp），否则 request context 中不会携带 span.Context()，下游调用无法延续 trace。
立即学习“go语言免费学习笔记（深入）”；
使用场景：Gin、Echo、标准 net/http 服务都需要显式包裹 handler。
- 标准
http.ServeMux：用otelhttp.NewHandler()包裹 handler 函数 - Gin：注册
gin.HandlerFunc(otelhttp.NewMiddleware("my-service").ServeHTTP)作为全局中间件 - 注意
otelhttp默认只记录状态码和路径，如需记录请求体/响应体，需自定义SpanOptions并谨慎控制采样率 - 避免对健康检查接口（如
/healthz）埋点 —— 高频调用会显著增加后端压力
客户端调用（HTTP/gRPC）必须传播 context
Span 能否跨服务串联，取决于 client 是否将当前 span context 注入请求头。OpenTelemetry 提供了标准传播器（如 tracecontext），但需要显式使用，Go 默认不自动做这件事。
常见错误现象：上游服务有 trace_id，下游服务 log 中全是 00000000000000000000000000000000。
- HTTP client 发起请求前，用
req = req.WithContext(otel.GetTextMapPropagator().Inject(req.Context(), propagation.HeaderCarrier(req.Header))) - gRPC client 直接使用
otelgrpc.Interceptor()，它会自动处理 context 传播和 span 创建 - 若用
http.Client.Do()手动调用，必须确保传入的req.Context()是从上游 span 派生的（例如span.SpanContext().TraceID().String()不能硬编码） - 避免在 goroutine 中丢弃原始 context —— 如
go func() { doSomething() }()会切断链路
OTLP 导出器配置不当会导致 trace 丢失或超时
otlphttp.Exporter 默认使用同步发送 + 无重试，网络抖动或 collector 不可用时，Span 会被直接丢弃，且不报错。这是生产环境 trace 数据断连的最常见原因。
性能影响：同步模式下，单次导出耗时超过 1s 会明显拖慢业务请求。
- 务必启用异步模式：用
sdktrace.NewBatchSpanProcessor()替代NewSimpleSpanProcessor() - 设置合理 batch 参数：
MaxExportBatchSize: 512，ScheduleDelayMillis: 5000，MaxQueueSize: 2048 - 开启重试：
WithRetry(otlphttp.RetryConfig{Enabled: true}) - Collector 地址建议用
http://otel-collector:4318/v1/traces（注意端口和路径），别漏掉/v1/traces - 本地开发可先用
stdoutexporter验证 Span 结构是否正确，再切到 OTLP
最容易被忽略的是：Span 的结束时机。手动调用 span.End() 前，必须确保所有子 Span 已结束、context 未被 cancel。defer 虽方便，但在 error early return 场景下容易遗漏 —— 建议统一用 span.End(span.WithStackTrace(true)) 并配合 linter 检查未结束的 Span。
