OpenTelemetry 语义约定迁移中的字段映射方法

OpenTelemetry 语义约定迁移的关键不是把旧字段名批量替换成新字段名，而是把“哪个 schema 产生了它、字段语义如何变化、哪些消费者还依赖旧字段”记录成一张可审计的映射表。官方 Schema 规范把 Schema URL 作为版本标识，消费者可以按目标 schema 转换收到的 telemetry。

官方地址：https://opentelemetry.io/docs/specs/otel/schemas/

先用 schema URL 固定迁移边界

一次迁移至少要有四列输入：信号类型、源 schema URL、属性名及类型、实际消费者。span、metric、log 和 resource 不要混在一张没有信号标记的清单里；同名字段在不同信号中可能承担不同语义。还要把稳定性、是否含敏感信息、是否参与采样或聚合一并记下。

建议先做一份小而明确的登记表：

把重命名、合并和拆分分开处理

最简单的情况是 rename：一个旧字段对应一个新字段，值的含义和类型不变。若两个旧字段合成一个新字段，就要写明优先级、缺省值和冲突处理；一个旧字段拆成多个字段，则要定义解析失败时保留什么。值归一化也不是 rename，例如枚举值、单位、大小写或资源属性层级发生变化时，必须保留转换规则。

# 示例：记录迁移契约；这里只表达映射意图，不代表某个采集器的现成配置
schema:
  source_url: https://opentelemetry.io/schemas/old
  target_url: https://opentelemetry.io/schemas/new
  mappings:
    - from: http.method
      to: http.request.method
      action: rename # 语义和类型不变时才使用 rename
    - from: client.address
      to: client.address
      action: normalize # 先脱敏，再统一格式；失败时保留缺省值
    - from: db.name, db.namespace
      to: db.namespace
      action: merge # 明确冲突优先级，不能静默覆盖

映射表中还应有 keep/drop 列。keep 表示旧字段仍有独立消费者，drop 表示它已确认不再被查询、告警或下游程序读取。对于高基数、敏感值和可能为空的属性，转换规则应和字段名一起评审，否则迁移后看似成功，成本和隐私风险却被隐藏。

用双发给消费端留出迁移窗口

生产系统通常先让目标字段成为主路径，同时在明确的兼容窗口内保留旧字段或旧版本输出。OpenTelemetry 的版本选择文档把 dual emit 作为分阶段迁移手段；当新旧字段冲突时，目标版本应优先，非重叠字段可以合并保留。这里的重点不是永久双写，而是给仪表盘、告警规则、采样条件和导出链路留出切换时间。

收口前至少复查四件事：新旧查询结果是否能对齐；聚合单位和枚举值是否一致；字段基数是否异常增长；敏感字段是否按目标约定继续脱敏。只有消费端已经改用目标字段、旧字段读取量归零且回滚方案仍可用，才适合关闭双发。

常见问题

字段只是改了名字，为什么还要记录 schema URL？

因为消费者需要知道数据来自哪个约定版本。没有版本边界，单看字段名无法判断转换是否已经完成。

两个旧字段合成一个新字段时最容易漏什么？

最容易漏冲突优先级和缺省值。两列同时存在、只有一列存在、两列都为空，都应有明确结果。

什么时候不能继续使用 rename？

类型、单位、枚举语义、敏感性或基数发生变化时，应该改成 normalize、merge、split 或自定义转换，并补充消费端验收。

旧字段可以马上删除吗？

不建议。先完成双发和查询迁移，观察一段兼容窗口，再依据读取量和回滚条件决定下线。

把字段映射当成版本迁移契约，迁移就能从一次容易误伤的全局替换，变成有源版本、有转换类型、有验收结果的可回滚变更。