OpenTelemetry 语义约定更新怎样影响链路字段

OpenTelemetry 语义约定更新，真正影响的不是一个“版本号”字段，而是链路数据的契约：Span 名称、属性键、属性值的规范集合、Metric 名称与单位，以及后端查询依赖的字段关系。当前官方语义约定总页显示为 1.45.0，但这不表示所有语言 SDK、自动埋点和 Collector 会在同一时间自动切换到所有新字段。判断升级影响时，要先确认具体 instrumentation 支持哪一版、字段处于什么稳定性，再决定保留旧字段、双发还是切换新字段。

官方语义约定入口：https://opentelemetry.io/docs/specs/semconv/

最稳妥的做法是先做“旧字段—新字段—采集条件—查询改动”四列映射，再开启迁移配置。只改看板里的字段名，往往会漏掉 Span 名称、采样时机、属性可选性和指标单位的变化。

先把“更新”拆成四类链路变化

我在维护链路字段时，最容易踩的坑是把“语义约定更新”理解成简单的 key 替换。官方版本与稳定性文档把语义约定看成 instrumentation 和分析工具之间的契约，覆盖资源、Span、事件、Metric 和日志中的一部分字段。一次更新至少要分别检查下面四类变化：

官方当前页面还列出 GenAI 语义约定已经移到独立仓库。类似变化说明：不能只盯着某个文档页面的标题，还要确认领域入口、生成代码版本和实际 instrumentation 的发布说明。对生产链路来说，“文档里存在字段”不等于“当前 SDK 默认会发字段”。

用 HTTP 迁移实例看字段怎样变化

HTTP 是最适合拿来做迁移演练的领域。官方 HTTP 稳定性迁移页明确列出了一批改名，例如 http.method 迁移到 http.request.method，http.status_code 迁移到 http.response.status_code，http.url 迁移到 url.full，客户端的 net.peer.name 迁移到 server.address。它还说明请求体大小字段的推荐级别会变化，网络协议字段也有新的命名关系。

这意味着查询迁移不能只做全局字符串替换。比如原来的错误率面板可能依赖 http.status_code，新的查询要确认后端是否已经收到 http.response.status_code；原来按主机分组的面板还要检查 server.address 是否仍表示同一个逻辑服务端，而不是把连接地址、代理地址和服务名混在一起。

# 旧字段 -> 新字段：先写清迁移关系，再改查询和告警
http.method -> http.request.method
http.status_code -> http.response.status_code
http.url -> url.full
net.peer.name -> server.address

# 这些字段还要记录采集条件，不能只记录名称
http.request.body.size -> opt-in / 检查采集开关
network.protocol.name -> 检查与 protocol.version 的组合

上面的文本是迁移清单示例，不是一次真实导出的 Span。真正落地前，要从当前 instrumentation 的文档或测试数据确认它是否支持这些字段，并把字段的稳定性和采集开关一并写进变更单。

用 opt-in 或双发给迁移留出窗口

当旧查询还没有全部改完时，不建议直接把生产 instrumentation 切成只发新字段。官方 HTTP 迁移规则提供了 OTEL_SEMCONV_STABILITY_OPT_IN：设置 http 表示只发稳定 HTTP 与网络语义约定，设置 http/dup 表示旧字段和稳定字段同时发出；没有设置时，instrumentation 可以继续保持原先默认行为。

# 第一阶段：保留旧查询，同时让 HTTP 新旧字段并存
export OTEL_SEMCONV_STABILITY_OPT_IN=http/dup

# 第二阶段：看板、告警和下游规则完成迁移后，只发稳定字段
export OTEL_SEMCONV_STABILITY_OPT_IN=http

# 发布前记录当前进程实际读取的配置，便于回滚和定位
printenv OTEL_SEMCONV_STABILITY_OPT_IN

如果多个领域一起迁移，可以按逗号组合领域值，但不要把“配置被接受”误认为“所有领域都支持”。当前版本选择规范还描述了声明式配置的 version、experimental 和 dual_emit；当声明式配置与环境变量同时存在时，声明式配置优先。某个 instrumentation 不支持请求的版本时，还可能回退到最近的已支持版本，因此发布记录必须写明“请求值”和“实际支持版本”。

双发也不是免费兼容层。它会增加字段数量、索引写入和查询歧义，尤其是同一逻辑属性同时出现两套名字时。迁移窗口应设置负责人和结束条件，例如新字段查询覆盖率、旧字段面板数量、数据量变化和回滚开关，而不是无限期保留 /dup。

把 schema URL 和后端查询一起纳入发布清单

Telemetry Schema 的作用是描述可被工具理解的字段演进，但它不能替代人工确认。官方稳定性文档明确指出，属性、Metric 和 Span 的改名应由 schema 文件描述；同时，当前规范还提示不要把 schema transformation 当成无需迁移的万能保障。我的做法是把下面四项作为一次发布的最小记录：

1. 记录 instrumentation、语言 SDK、Collector 和语义约定支持版本，不只记录应用版本。
2. 把旧键、新键、稳定性、是否 opt-in、是否双发以及值域变化写成字段映射。
3. 在测试环境检查 Span 名称、属性键、Metric 名称和单位，再逐个改写查询、告警和采样条件。
4. 保存 schema URL、配置快照、数据量变化和回滚配置；旧字段下线前保留一条可以执行的回退路径。

# 用发布记录表达本次迁移意图；实际支持范围以 instrumentation 文档为准
semconv_migration:
  domain: http
  requested_mode: http/dup
  old_fields: [http.method, http.status_code]
  new_fields: [http.request.method, http.response.status_code]
  rollback_mode: default
  query_owner: observability-team

YAML 里的数组只是变更单示例，不是 OpenTelemetry 的通用配置文件。它的价值在于把字段迁移的责任边界写清楚：应用负责发什么，Collector 是否改写，后端查询读什么，谁在什么条件下关闭旧字段。

官方版本选择入口：https://opentelemetry.io/docs/specs/semconv/configuration/version-selection/

HTTP 迁移说明：https://opentelemetry.io/docs/specs/semconv/non-normative/http-migration/

常见问题

语义约定版本更新后，旧字段会立即消失吗？不一定。具体行为取决于 instrumentation 的支持版本、默认稳定性和 opt-in 配置；先看该组件的迁移说明。

开启 http/dup 后是不是所有查询都不用改？不是。它只是提供迁移窗口，查询仍应逐步切到新字段，并关注双发造成的数据量和聚合重复。

有 schema URL 就能自动修复所有看板吗？不能。schema 描述可转换的演进关系，但看板、告警、采样和自定义过滤仍需要按实际数据验证。

为什么文档里的新字段在我的 Span 中找不到？常见原因是 SDK 或 instrumentation 版本较旧、字段需要 opt-in、配置被声明式设置覆盖，或者当前组件尚未实现该稳定约定。

OpenTelemetry 语义约定更新影响链路字段时，先确认“谁发字段、发哪个版本、是否稳定”，再处理查询和看板。把字段映射、迁移配置、schema URL、数据量和回滚开关放在同一张发布清单里，升级才不会停留在改几个字符串。