必须使用 echootel.Middleware,而非手动 StartSpan 或误用 otelhttp.NewHandler;它自动解析 traceparent、注入带 span 的 context 到 echo.Context,并填充 http.route 等语义属性。

echo.Context 里拿不到有效 span 怎么办
根本原因是没用 echootel.Middleware,而是手动调 otel.Tracer().Start() 或者把 otelhttp.NewHandler 塞进 echo.Use()。这两种做法都会导致 echo.Context 和 OpenTelemetry 的 context.Context 脱节——你从 c.Request().Context() 拿到的不是带 span 的 context,span.SpanContext().IsValid() 返回 false,所有后续操作都静默失效。
正确路径只有一条:用官方维护的 echootel.Middleware,它会在请求进入时自动从 header 解析 traceparent,创建 server span,并把带 span 的 context 注入到 echo.Context 的底层 context.Context 中。
- 别自己写中间件去调
tracer.Start():漏掉http.status_code、http.route、net.peer.ip等关键属性,span name 固定为HTTP GET,不是真实路由 - 别把
otelhttp.NewHandler当 echo 中间件用:它包装的是http.Handler,不是echo.HandlerFunc,会导致路由参数丢失、c.Param()为空、c.Path()不准确 - 确保
echootel.Middleware是第一个注册的中间件(即最早调用e.Use()),否则上游自定义中间件可能提前消费或覆盖 context
echo.Context 传给 goroutine 后 span 断了
Go 的 context.Context 不会自动跨 goroutine 传播,echo.Context 本身只是个 wrapper,底层 context 如果没显式传递,子协程拿到的就是空 context,otel.Tracer().Start() 创建的必是 root span,trace_id 全 0。
必须显式把 echo.Context 里的 context 传进去,且用 otel.GetTextMapPropagator().Inject() 在出向调用前注入 header(比如 HTTP client 或 DB 查询)。
- 启动 goroutine 时用
go func(ctx context.Context) { ... }(c.Request().Context()),而不是go func() { ... }() - 在子协程内发起 HTTP 请求,要用
otelhttp.NewClient()或手动req = req.WithContext(ctx)+propagator.Inject() - 数据库查询必须用
otelsql插件,不能在 goroutine 里手写span.Start()/End():后者只包住 SQL 执行,不包连接池等待、驱动解析等真实耗时
service.name 为空、Jaeger 里看不到服务聚合
现象是 trace 能看到,但所有 span 都归到 unknown_service 下,无法按服务筛选或统计。这是因为 TracerProvider 初始化时没传 resource.Resource,OpenTelemetry 默认不会填任何语义属性。
Echo框架 5.1.0 版本源码包下载,适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
必须在 main() 开头构造 resource 并传给 sdktrace.NewTracerProvider(),且 service.name 是必填项。
- 构造 resource 示例:
resource.NewWithAttributes(semconv.SchemaURL, semconv.ServiceNameKey.String("user-service")) - 别漏掉
otel.SetTextMapPropagator(propagation.TraceContext{}):没有它,跨服务 header 无法解析,下游收不到 traceparent - 别在
init()里初始化 provider:单元测试并发跑时可能 panic;也别在 handler 里 new 多个 provider,会导致采样错乱、exporter 连接泄漏
本地调试时 trace 完全不出现
最常见原因是 TracerProvider 初始化失败但被静默忽略——比如 OTLP exporter 地址不通、Jaeger agent 不在 localhost:6831、或者忘了调 otel.SetTracerProvider()。此时 otel.Tracer() 返回的是 noop 实现,span.End() 什么也不做,程序无报错、日志无 trace_id、Jaeger 空空如也。
本地开发阶段,优先用 stdouttrace.NewUnstarted() 替代网络 exporter,终端直接打印 JSON 格式 span,秒级验证链路是否通。
- 启用 stdout 输出示例:
sdktrace.NewTracerProvider(sdktrace.WithSpanProcessor(otlptrace.NewSimpleSpanProcessor(stdouttrace.NewUnstarted()))) - 加一行日志验证:
log.Printf("traceID: %s", span.SpanContext().TraceID().String()),如果输出全是 0,说明 span 无效 - curl 测试时手动带 header:
curl -H 'traceparent: 00-12345678901234567890123456789012-1234567890123456-01' http://localhost:8080/api/users,再看服务端能否提取出非零 trace_id
最易被忽略的点是:TracerProvider 必须在 main() 第一行完成注册,且 otel.SetTracerProvider() 和 otel.SetTextMapPropagator() 缺一不可——少一个,整个链路就退化成单点埋点,再精细的业务逻辑也无法串联起来。










