必须在main()开头调用otel.settracerprovider，否则所有tracer().start()返回noop span，导致trace丢失、无报错、日志无线索；需早于http server启动，禁用init()，配采样器、传播器及exporter，并确保span.end()和context透传。
otel.SetTracerProvider 必须在 main() 开头调用，否则所有 Tracer().Start() 返回的都是 noop span —— 看不到 trace、不报错、查日志也找不到线索，这是最常卡住新人的第一步。
初始化 TracerProvider 不能晚于 HTTP server 启动
Go 的 init 函数执行顺序不可控，如果把 OTel 初始化塞进 init，而 HTTP handler（比如 http.HandleFunc）注册得早，就可能出现“handler 已就绪，但 tracer provider 还没 set”的状态。后果是：请求进来后 otel.Tracer("xxx").Start(r.Context(), "handler") 拿到的是空 span，后续所有 span.AddEvent、span.End() 都无效。
正确做法是：在 main() 最开头显式初始化，并确保 otel.SetTracerProvider 成功执行：
func main() {
tp := trace.NewTracerProvider(
trace.WithBatcher(exporter),
trace.WithSampler(trace.AlwaysSample()),
)
otel.SetTracerProvider(tp) // ← 这行不能漏，也不能被 defer 或条件包裹
defer func() { _ = tp.Shutdown(context.Background()) }()
http.Handle("/", otelhttp.NewHandler(http.HandlerFunc(handler), "root"))
http.ListenAndServe(":8080", nil)
}
-
exporter推荐先用stdouttrace.NewExporter，不是loggingexporter；前者输出结构化 JSON，后者只打字符串日志，没法看 span 层级 - 采样器别用默认值——
trace.NeverSample()会让所有 span 被丢弃，本地调试建议用trace.AlwaysSample() -
tp.Shutdown()必须调，否则程序退出时 batch exporter 里未 flush 的 span 会丢失
HTTP 中间件必须用 otelhttp.NewHandler，别自己解析 traceparent
手动写中间件提取 traceparent header 容易漏兼容性细节：旧系统可能发 b3 格式，前端 SDK 可能用 uber-trace-id，而 OpenTelemetry 默认只认 traceparent。结果就是链路在第一个服务就断掉。
解决方法是提前注册复合 propagator，并让 otelhttp.NewHandler 自动处理：
otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(
propagation.TraceContext{},
propagation.B3{},
))
http.Handle("/api", otelhttp.NewHandler(yourHandler, "api"))
-
otelhttp.NewHandler会自动从 request header 提取 context、创建 child span、注入 response header，比手写中间件更可靠 - 它内部调用
otel.GetTextMapPropagator().Inject()写回traceparent，下游服务才能继续链路；漏这步，跨服务就断 - 不要在 handler 里直接用
r.Context()创建新 span——要先用trace.SpanFromContext(r.Context())拿当前 span，再基于它 Start 子 span
goroutine 里的 span 必须传 context，不能用 context.Background()
Go 的 context 不跨 goroutine 自动传播。HTTP handler 里起一个 go func() {}()，里面调 Tracer.Start(context.Background(), ...)，生成的就是 root span，和上游完全无关。典型现象：Jaeger 里看到两个孤立的 trace，中间没父子关系。
修复方式只有一条：显式传入带 span 的 context：
func handler(w http.ResponseWriter, r *http.Request) {
ctx := r.Context()
_, span := otel.Tracer("handler").Start(ctx, "handle-request")
defer span.End()
go doWork(ctx) // ← 必须传 ctx，不是 context.Background()
}
func doWork(ctx context.Context) {
_, span := otel.Tracer("worker").Start(ctx, "background-job")
defer span.End()
// ...
}
-
span.End()是强制操作，不是可选装饰——它触发采样判定、事件 flush、属性合并；漏掉会导致内存缓慢上涨（batch exporter 缓冲区堆积）、trace 数据丢失 - 数据库、Redis、gRPC 调用也要用 instrumented client（如
go.opentelemetry.io/contrib/instrumentation/database/sql），原生 client 不会自动继承 context - 第三方库回调函数（比如 ent hook、gorm callback）里拿不到有效 span？那就手动用
otel.GetTextMapPropagator().Inject()补 header
OTLP exporter 连不上 collector 时先检查三件事
本地能看到 stdout 输出 span，但 Jaeger / Tempo 里空空如也，90% 是 OTLP 配置或网络问题，不是代码 bug。SDK 默认失败静默，不会 panic，也不会 log 错误。
快速定位步骤：
- 确认 collector 地址协议和端口：HTTP endpoint 是
http://localhost:4318，gRPC 是localhost:4317；混用会连不上 - 用
curl -v http://localhost:4318/v1/traces测试 collector 是否响应 200；返回 404 是正常（路径存在但没数据），返回 connection refused 就说明 collector 没起来或端口不对 - 检查 exporter 初始化是否带超时：默认 5s，短时间网络抖动就会丢 trace；可加
otlphttp.WithTimeout(30*time.Second)观察是否恢复
真正难的不是配通，而是配稳：异步任务 span 没 close、propagator 没设全、context 没传进 goroutine——这些错误不会立刻报错，但会让 trace 断在某个看似无关的角落。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
