beego中间件中必须手动创建并透传span，否则子span断链；需从header提取trace context、用contextwithspan注入request context、defer调用finish()，且异步goroutine须显式传递span.context()。
Beego 中间件里必须手动创建并透传 Span
Beego 没有像 Gin 那样成熟的官方 OpenTracing 中间件，StartSpan 之后不绑定到 context.Context，后续业务逻辑就拿不到当前 span，子 span 全部断链。常见错误是只调用 tracer.StartSpan()，但没把生成的 span 注入到 Beego 的 Controller.Ctx.Request.Context() 中。
正确做法是：在中间件中先从 HTTP header 提取上游 trace context（用 tracer.Extract(opentracing.HTTPHeaders, opentracing.HTTPHeadersCarrier(r.Header))），提取失败才新建 root span；然后用 opentracing.ContextWithSpan() 包装 request context，并通过 ctx.WithContext() 覆盖原 context；最后记得在 defer 里调用 span.Finish()。
别在 span.Finish() 前写 response body 或调用 ctx.ResponseWriter.Write()，某些 Beego 版本会 panic —— 因为 writer 已被提前关闭或 reset。
Reporter 配置错端口会导致 span 静默丢弃
本地开发时习惯配 LocalAgentHostPort: "localhost:6831"，但 jaegertracing/all-in-one:latest 默认监听的是 6832/udp（不是 6831）。如果 Agent 没跑、端口不匹配、防火墙拦截 UDP，span 就完全不上报，Jaeger UI 里查不到任何数据，也没有报错日志 —— 这是最容易被忽略的“黑盒失败”。
调试阶段建议开启：Reporter.LogSpans: true，这样能在控制台看到每条 span 的 JSON 输出，确认是否创建成功、是否尝试上报；生产环境必须关掉，改用 BufferFlushInterval 控制批量 flush 频率，避免高频小包打满网卡。
若跳过 Agent 直连 Collector，要用 jaeger.NewRemoteReporter + transport.NewHTTPTransport，此时 endpoint 是 http://jaeger-collector:14268/api/traces，端口是 14268（HTTP 接收），不是 UDP 端口。
Beego 的异步 goroutine 里 trace context 会丢失
Beego 的 Controller.ServeHTTP 是同步执行的，但一旦你启动 goroutine 做异步任务（比如发 MQ、调第三方 API、写日志归档），默认情况下新 goroutine 拿不到父 span 的 SpanContext，它会变成孤立的 root span，链路就此断裂。
必须显式传递：span.Context() 作为参数传入 goroutine，再用 tracer.StartSpan("async-task", opentracing.ChildOf(span.Context())) 创建子 span；不能依赖闭包捕获 controller 层的局部变量 span，因为 Go 的 goroutine 启动时机不确定，span 可能已被 finish。
更稳妥的方式是用 opentracing.ContextWithSpan(ctx, span) 构造带上下文的 context.Context，再传给 go func(ctx context.Context) { ... }(ctx)，子 goroutine 内再用 opentracing.SpanFromContext(ctx) 提取。
gRPC 和 HTTP 混合调用时 header 透传不兼容
Beego 服务作为 HTTP client 调 gRPC 服务时，uber-trace-id header 不会被 gRPC 自动识别；同样，gRPC client 调 Beego HTTP 接口时，metadata 里的 trace 字段也不会自动映射成 HTTP header。这条链路上下文不打通，trace 就断在第一跳。
手动注入方式分两步：
• 发起 gRPC 调用前，用 tracer.Inject(span.Context(), opentracing.HTTPHeaders, opentracing.HTTPHeadersCarrier(headers)) 把 trace context 写进 metadata.MD；
• Beego 接收 gRPC 请求（如通过 grpc-gateway）时，要从 metadata.MD 中取出 uber-trace-id 等字段，构造 http.Header，再调用 tracer.Extract() 恢复 context。
注意：uber-trace-id 是 Jaeger 旧格式，OpenTelemetry SDK 默认用 traceparent，混用时需统一格式或启用兼容模式，否则 Extract 失败后 fallback 新建 root span，链路照样断。
