OpenTelemetry 的 span 属性虽可 Set，但在自动埋点中间件（如 otelgin.Middleware）中易被覆盖或未及时 flush；正确做法是在 span 创建时注入 version，如 Gin 中按路由分组绑定独立 Tracer 或在 SpanNameFormatter 中解析路径提取版本，gRPC 则需在 UnaryInterceptor 中解析 method 名并设 attribute；最终应将版本固化到 resource 而非 runtime attribute。
为什么直接在span上SetAttributes("version", "v1")会失效
OpenTelemetry 的 span 属性是只读快照，span.SetAttributes() 确实能写入，但若你用的是 otelgin.Middleware 或 otelhttp.NewHandler 这类自动埋点中间件，它们会在 handler 入口就创建 server span 并结束——你手动 Set 的 version 属性可能被后续的自动属性（如 http.route）覆盖，或根本没来得及 flush 就结束了。更常见的是：多个中间件嵌套时，span 生命周期由最外层控制，你在内层 handler 里 Set 的属性，可能属于另一个子 span，而非 root server span。
在 Gin 中给 v1/v2 路由打上正确 version 标签的实操方式
别依赖中间件后 Set，而是在 span 创建时就注入 version。Gin 的 otelgin.Middleware 支持传入自定义 otelgin.Option，其中 otelgin.WithSpanNameFormatter 和 otelgin.WithFilter 不够用，真正有效的是 otelgin.WithPublicEndpoint 配合路由分组识别——但更稳的方式是自己封装一层：
- 用
router.Group("/v1")和router.Group("/v2")分开注册，每个 group 初始化时绑定对应 version 的Tracer - 为每个版本构造独立的
Tracer实例：otel.Tracer("user-service/v1")和otel.Tracer("user-service/v2")，这样 service.name + tracer name 组合天然区分版本 - 如果必须共用同一个 TracerProvider，则在
otelgin.Middleware的otelgin.WithSpanNameFormatter回调里解析r.URL.Path提取版本前缀，并返回带版本的 span name，例如"HTTP GET /v1/users" - 避免用
context.WithValue()存 version 字段再从 context 取——otelgin默认不读这个，得自己重写中间件逻辑
gRPC UnaryInterceptor 怎么让 v1/v2 方法带上 version 标签
gRPC 没有路径前缀概念，version 通常体现在方法名（如 /api.v1.UserService/GetUser）或 metadata。OpenTelemetry 的 otelgrpc.UnaryServerInterceptor 默认只提取 trace 上下文，不解析 method 名。要加 version 标签，必须显式拦截：
- 在 interceptor 内部用
fullMethod := grpc.MethodFromContext(ctx)解析完整方法路径 - 正则匹配
^/api\.(\w+)\.UserService/或类似规则提取v1、v2 - 调用
span.SetAttributes(attribute.String("api.version", version))—— 注意这必须在 span 创建后、handler 执行前完成 - 别在 handler 里做这事：gRPC 的 span 生命周期由 interceptor 控制，handler 返回后 span 就 close 了
- 如果用了 proto 的包版本（如
package api.v2;），可直接从fullMethod截取strings.Split(fullMethod, ".")[1]，比硬编码正则更可靠
容易被忽略的采样与聚合陷阱
版本标签不是加完就完事。如果你用 ParentBased(TraceIDRatioBased(0.1)) 采样，而 v2 流量只占 5%，那 v2 的 trace 实际采样率只有 0.5%；Prometheus 的 traces_sampled_total{service_name="user-service",api_version="v2"} 会严重偏低。更麻烦的是，Jaeger/Tempo 的 UI 按 service.name 聚合时，默认不展示 api.version，你得手动加 filter 或改 UI 配置。真正的解决点只有一个：所有版本相关的标签，必须在 tracer 初始化阶段就固化进 resource，而不是 runtime 动态设 attribute。
立即学习“go语言免费学习笔记（深入）”；
