必须在main()开头一次性完成TracerProvider注册、传播器设置和导出器初始化,否则所有tracer.Start()返回noop span,链路静默失效;TracerProvider须全局唯一、显式传入service.name,HTTP/gRPC/DB必须用对应OTel中间件或封装器。

必须在 main() 函数最开头一次性完成 TracerProvider 注册、传播器设置和导出器初始化,否则所有 tracer.Start() 都返回空 span——不报错、无日志、链路静默消失,这是 90% 的项目卡点。
TracerProvider 必须在 main() 开头注册且仅一次
OpenTelemetry Go SDK 不 fallback 到默认实现;未调用 otel.SetTracerProvider() 时,otel.Tracer() 返回的是 noop tracer,所有 span 创建都静默失败。
- 别在
init()里注册:Go 的init执行顺序不可控,HTTP server 可能比 tracer provider 先启动 - 别在 handler 或中间件里临时 new:
sdktrace.NewTracerProvider()会导致多个 provider 竞争、exporter 连接泄漏、采样逻辑混乱 - 必须显式传入
resource.Resource,至少带service.name属性,否则 Jaeger / Tempo 无法按服务分组 - 本地调试建议用
stdoutexporter.NewUnstarted()+.Start(),终端直接输出完整 span JSON,比查日志快得多
HTTP 框架必须用对应 OTel 中间件,不能手写 header 解析
手动调 req.Header.Get("traceparent") + tracer.Start() 看似可行,实则漏掉三类关键信息:跨 goroutine 的 context 传播、net.peer.ip 等语义属性、自动状态码记录(4xx/5xx 不会打 tag)。
-
otelhttp.NewHandler必须包裹最终业务http.Handler,不是中间件链里的某一层 - Gin 必须用
ginotel.Middleware(),否则 span name 是GET /而非GET /users/:id - Echo 必须用
echootel.Middleware(),同理解决路由名问题 -
otelhttp.NewHandler第二个参数(span name)不能为空字符串,Jaeger 会静默丢弃
数据库和 gRPC 调用必须走 instrumented driver 和拦截器
在 db.Query() 前后自己 tracer.Start()/End(),测出来耗时远小于实际 SQL 执行时间——因为没捕获连接池等待、驱动解析、网络往返等环节。
- MySQL 必须用
github.com/go-sql-driver/mysql,不能用modernc.org/sqlite等纯 Go 驱动变体(hook 点不兼容) - 初始化 DB 时必须用
sql.OpenDB(otel.WrapDriver(driver, &otel.Config{})),而非sql.Open() - gRPC 客户端需配
otelgrpc.UnaryClientInterceptor(),服务端需配otelgrpc.UnaryServerInterceptor();otelhttp对 gRPC 完全无效 - 异步任务(goroutine)中 span 消失的主因是没传递带 span 的
context.Context;必须用trace.ContextWithSpan(ctx, span)注入,不能用context.WithValue()
OTLP 导出器连不上 Jaeger 的常见配置坑
日志没报错但 Jaeger 界面始终空白,根本问题常出在连接配置或 collector 启动参数上。
-
otlptracegrpc.New的WithEndpoint("localhost:4317")在 Docker 容器内运行时,localhost指向容器自身,不是宿主机;应改用host.docker.internal:4317(Mac/Windows)或宿主机真实 IP(Linux) - 默认
jaegertracing/all-in-one镜像只开 6831/14268 端口,需显式启用 OTLP:docker run -d --name jaeger -p 16686:16686 -p 4317:4317 -e COLLECTOR_OTLP_ENABLED=true jaegertracing/all-in-one:latest - gRPC 连接未设超时或重试,网络抖动时 silently fail;建议加
otlptracegrpc.WithDialOption(grpc.WithBlock())便于快速失败定位 - 必须调用
otel.SetTextMapPropagator(),推荐用propagation.NewCompositeTextMapPropagator(propagation.TraceContext{}, propagation.B3{})兼容新老系统
最易被忽略的点是:所有中间件里创建 child span,必须从 r.Context() 取 context,严禁用 context.Background();而跨 goroutine 场景下,context.Context 不自动传递,DB 驱动也不读 context 里的 span——这是底层事实,不是 bug。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!











