必须在main()开头注册TracerProvider并调用otel.SetTracerProvider,否则所有span为nil且静默失效;需设resource.service.name、用otelhttp.NewHandler包裹HTTP、otelsql.InjectDriver接入数据库、显式传递context。

必须在 main() 开头注册 TracerProvider,否则所有 trace 都静默丢失——不报错、不打日志、Jaeger 里空空如也。
TracerProvider 初始化必须放在 main() 最前面
OpenTelemetry Go SDK 不会 fallback 到默认实现。没调 otel.SetTracerProvider(),otel.Tracer() 就返回 noop tracer,所有 Start() 调用都静默失败。
- 别写在
init()函数里:Go 的 init 执行顺序不可控,HTTP server 可能比 provider 先跑起来 - 别在 handler 或中间件里 new:会导致多个 provider 竞争、exporter 连接泄漏、采样逻辑混乱
- 必须显式传入
resource.Resource,至少带service.name属性,否则 Jaeger / Tempo 无法按服务分组 - 本地调试建议用
stdoutexporter.NewUnstarted()+.Start(),它直接输出完整 span JSON,比查日志快得多
Echo 中间件必须用 echootel.Middleware()
手写 req.Header.Get("traceparent") + tracer.Start() 是典型误区:漏掉三类关键信息——跨 goroutine 的 context 传播、net.peer.ip 等语义属性、自动状态码记录(4xx/5xx 不会打 tag)。
Echo框架 5.1.0 版本源码包下载,适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
-
echootel.Middleware()会正确解析traceparent并注入 server span,span name 是GET /users/:id而不是笼统的GET / - 出向 HTTP 调用必须替换 Transport:
http.DefaultClient.Transport = otelhttp.NewTransport(http.DefaultTransport),否则下游 span 断开,只看到无意义的HTTP GET - 若跳过这一步,所有下游调用 span 都缺
http.status_code、net.peer.ip,且 duration 不准
数据库调用不能手动埋点,必须走 instrumented driver
在 db.Query() 前后自己 tracer.Start()/span.End(),测出来耗时远小于实际 SQL 执行时间——因为没捕获连接池等待、驱动解析、网络往返等环节。
- MySQL 必须用
github.com/go-sql-driver/mysql,不能用modernc.org/sqlite等纯 Go 驱动变体(hook 点不兼容) - 初始化 DB 时必须用
sql.OpenDB(otel.WrapDriver(driver, &otel.Config{})),而非sql.Open() - span 名默认是
SELECT FROM users,生产环境务必配WithSpanNameFormatter改成固定名,避免高基数打爆 backend - GORM v1.25+ 内置 OTel 支持,但需显式启用
gorm.WithOpentelemetry(),底层仍依赖上述 SQL driver 注册
最容易被忽略的是 TracerProvider 的注册时机和全局唯一性——它不像日志或配置可以“后面补”,一旦 server 启动后再注册,之前所有请求的链路就永远断了,且没有任何提示。










