不注册TracerProvider,所有span均为nil且静默失效;必须在main()首行注册全局唯一TracerProvider并调用otel.SetTracerProvider和otel.SetTextMapPropagator,HTTP用otelhttp.NewHandler、出向用otelhttp.Transport、DB用otelsql.InjectDriver,严禁手动解析traceparent或context.Background()。

不注册 TracerProvider,所有 span 都是 nil,程序不报错但链路完全不可见——这是最常被忽略的“静默失效”。
TracerProvider 必须在 main() 开头注册且全局唯一
Go 的 otel.Tracer() 调用永远不会 panic,但若没提前设置 sdktrace.TracerProvider,它返回的 span 永远为 nil。HTTP 中间件不生效、日志里没有 trace_id、数据库调用没 span,全因这一步缺失。
- 必须在
main()函数第一行(或紧随init()之后)完成注册,早于任何 HTTP server 启动、goroutine 启动、DB 连接初始化 - 不能放在某个 handler 或中间件里临时 new,否则多个 provider 冲突,采样逻辑错乱、exporter 连接泄漏
- 别用
init():单元测试并发调用时可能 panic;也别在子包里分散注册,确保全局只有一份 - 注册后必须显式调用
otel.SetTracerProvider(tp)和otel.SetTextMapPropagator(propagation.TraceContext{}),缺一不可
HTTP 入口必须用 otelhttp.NewHandler,不是手写 extract + StartSpan
自己解析 req.Header.Get("traceparent") 再调 tracer.Start(),会漏掉关键语义:跨 goroutine 传播失败、net.peer.ip 缺失、状态码不自动记录、span name 固定为 HTTP GET 而非真实路由。
-
otelhttp.NewHandler是 Go 生态中唯一正确绑定 HTTP 生命周期的封装:自动提取 header、注入 context、命名 span 为GET /api/users/:id、在WriteHeader后精准结束 - Gin 用户必须用
ginotel.Middleware,不能gin.Use(otelhttp.NewHandler(...)),否则路由参数丢失,span name 变成GET / - Echo 用户同理,用
echootel.Middleware;自定义中间件里起 child span,必须从r.Context()取 context,不能用context.Background()
出向 HTTP 调用必须用 otelhttp.Transport,不是改 http.DefaultClient
入向用了 otelhttp.NewHandler,但出向还用原始 http.Client,链路只有一跳——下游服务收不到 traceparent,span 直接断裂。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器,提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象,支持命名依赖等
立即学习“go语言免费学习笔记(深入)”;
- 正确做法:
client := &http.Client{Transport: otelhttp.NewTransport(http.DefaultTransport)} - 千万别直接赋值
http.DefaultClient = &http.Client{...}:会影响其他未 instrument 的库(如某些 SDK 内部 HTTP 调用),且无法隔离采样策略 - 若用 AWS SDK Go v2 等第三方库,确认它支持传入自定义
http.Client;不支持就换otelaws插件,否则链路必断
数据库追踪必须用 otelsql.InjectDriver,不是手动 Start/End
在 db.Query() 前后手动调 tracer.Start()/span.End(),span duration 会严重低估:漏掉连接池等待、驱动解析、TLS 握手等耗时,且不带 SQL 参数脱敏能力。
- 必须用
go.opentelemetry.io/contrib/instrumentation/database/sql,注册时调sql.OpenDB(otelsql.InjectDriver(driver, ...)),不是sql.Open() - MySQL 驱动必须用
github.com/go-sql-driver/mysql;modernc.org/sqlite等纯 Go 驱动变体不兼容 hook 点 - span 名默认是
SELECT FROM users WHERE id = ?,生产环境需用otelsql.WithSpanNameFormatter替换为固定名,避免高基数
真正难的不是埋点,而是 context 传递不中断——goroutine 启动、channel 发送、callback 回调,任何一个环节没显式传入带 span 的 context,链路就断了。别假设闭包能捕获,得亲手塞进去。

















