OpenTelemetry 语义约定 v1.20 到 v1.27:五处改名,悄悄弄坏你的每一块仪表盘

OpenTelemetry 语义约定 v1.20 到 v1.27 迁移指南封面图

一次语义约定改名是一行 diff;一次语义约定迁移,是跨五种文件类型的全代码库搜索,而那五种文件你可能根本不知道在自己手里。当 OpenTelemetry 的 span 从语义约定 v1.20 迁到 v1.27,大约有三十个属性名发生变化。改名表是公开的、完整的、枯燥的。不枯燥的是发现其中一半用法躺在 Grafana 仪表盘的 JSON 里、Collector 的 transform 配置块里,以及一个由你从没共事过的团队维护的 Java 服务里。OpenTelemetry 语义约定 v1.20 → v1.27 属性迁移工具存在的意义,就是把那场搜索从一周压成一次操作,并且老实告诉你哪些部分它拒绝自动化。

v1.20 到 v1.27 之间究竟改了什么

语义约定的版本节奏,独立于使用它的 SDK 和 Collector。v1.20 实际上已是 HTTP span 属性仍带实验状态的最后一个修订版。v1.23.1 把 HTTP 提升为 stable,并在同一次发布里把这个组里的名字大多换掉,因为 stable 就是名字停止变动的时刻,改名恰好发生在它被允许停下来的那一点上。v1.24.0 把数据库组推进了一步。v1.27.0 收尾消息组。

这就造出一个没人预料得到的迁移面。实践中不存在 v1.20 到 v1.27 的单次跳跃,因为团队升级 SDK 有自己的时间表,升级 Collector 又有另一张。你真正面对的是一个矩阵:三种可能的源版本、三种可能的目标版本,每一对的属性差异都不相同。只认识两端的迁移工具,会在矩阵中段默默给出错误答案,所以有用的输入是版本对,不是单个下拉框。

弄坏每一块仪表盘的五处改名

五处一一对应的改名,解释了约定升级之后面板损坏的绝大多数情况。

v1.20 到 v1.27 之间五处 OpenTelemetry 语义约定属性改名
  • http.method 改为 http.request.method
  • http.status_code 改为 http.response.status_code
  • http.url 改为 url.full
  • db.system 改为 db.system.name
  • messaging.destination 改为 messaging.destination.name

每一处都只是机械操作。伤害不来自改名本身,来自滞后。一块按 http.method 写的 Grafana 面板,在 SDK 升级之后还能欢快地渲染好几个月,因为在 Prometheus 风格的查询里,属性缺失通常求值为空序列,而不报错。你会在一次事故里发现它,或者在一次容量评审里,或者从同事那句「服务延迟面板怎么一直平在零」里发现。

第二个结构性问题在于,url.full 根本不是精神上的改名。旧的 http.url 带完整请求 URL,含查询串。url.full 带绝对 URL,但不含查询串和片段,这是刻意的防数据泄漏修正。任何依赖嵌在这个属性里的查询参数的仪表盘或记录规则,就算改名成功,行为也会变。

先读 diff,再写修复

操作顺序比听起来重要得多。跑完迁移,先读逐属性的 diff 统计,再碰任何一个文件。这些统计回答一个靠肉眼绝对回答不了的问题:每个被改名的属性到底有多少处用法。

http.method 计数很高是好消息,意味着一次机械操作就能修完,评审也轻松。计数为零比计数很高更值得注意,因为它通常说明这个名字埋在抓取器默认够不到的地方,比如 Grafana 的 JSON 字符串,或者一段不在粘贴源码里的 Collector YAML。

未映射属性报告才是真正的交付物。它列出你用过的每一个没有自动映射的属性,按后文描述的三类结果分开。大多数团队会发现,真正的工程工作量在这份清单上,不在改名表上。

Collector transform 不是查找替换

每一处改名都有一个 Collector 侧的答案,而如果你第一反应就是伸手去拿它,那是个陷阱。一条 OpenTelemetry Collector 的 transform 语句,可以在摄取时用 rename_attribute 动作改名,动作写在 trace_statements 条目里,作用域是 span 上下文。它第一次就能跑通,不需要发布应用,而它建立的心智模型恰好是错的。

在 Collector 里改过名的属性,是新名字套着旧数据。你的应用源码还在发 http.method,你本地的调试会话还在显示 http.method,下一个在终端或性能剖析器里看 trace 的人,看到的名字在已发布的代码里根本搜不到。更糟的是,Collector 配置成了正确性的承重结构,于是回滚一次 Collector,下游所有地方就静悄悄地恢复了旧名字。

把 Collector transform 当作你没有权限的服务的过渡桥,而不是目的地。生成它,应用到第三方服务上,同时排期做源码侧的修复。

未映射属性才是真正的工作

工具不会自动处理的东西,全部落在三类里,类别决定它吃掉你多少时间。

三类未映射的 OpenTelemetry 属性,以及解决每一类各自要付出多少

第一类是删除:有些 v1.20 属性在 v1.27 里没有对应物,因为约定作者判定这个概念定义不清或者对隐私不友好。http.host 是常见例子,它把服务器名和端口混在一起,替代方案把这个概念拆开了。这里没有唯一正确答案,所以警告是唯一诚实的输出,你得逐个服务判断这个属性是不是承重的。

第二类是人工拆分:一个旧属性变成两个新属性,任何自动工具在不知道你的拓扑的情况下,都判断不了哪一半该进哪个名字。net.peer.name 拆成客户端地址和服务器地址是典型例子,它算客户端还是服务器取决于调用方向,而这是抓取器不掌握的上下文。

第三类是仪表盘字符串:嵌在 JSON 值里的属性名是文本,不是代码,源码级改名够不着它。这是对另一批文件做的另一趟处理,也是最常被跳过的那一趟。

仪表盘也是 JSON,而且更难缠

Grafana 仪表盘把属性名至少存在四个不同的地方,只重写查询文本的迁移,仍然会留下一块坏掉的面板。

面板查询是最明显的一处。第二处是数据源覆盖块,旧名字在那里作为键出现,不是作为值。第三处是模板变量,它通常含一个匹配属性名的正则,于是匹配集一空就静默失败。第四处是注解定义,它很容易被漏掉,因为迁移时几乎没人打开它。

工具把这当成一个显式的可选项来处理:把同一张改名表应用到 JSON 字符串值内部。结构化重写 JSON 和文本重写属性名是两种操作,失败模式也不同。仪表盘进了版本库就打开它;仪表盘只活在共享的 Grafana 工作区里就关掉,那种情况下的脚本化编辑是权限问题,不是解析问题。

一份经得起代码评审的迁移清单

一份能过评审的迁移有它的形状,而这个形状主要关乎顺序和证据,不关乎聪明。

七步 OpenTelemetry 语义约定迁移清单,按代码评审的要求排列
  1. 按你实际要跨越的版本对跑迁移,而不是按两端。
  2. 读 diff 统计,确认高计数的属性与你对代码分布位置的预期相符。
  3. 动手编辑之前,把未映射报告分诊成删除、拆分、仪表盘字符串三类。
  4. 在你拥有的服务里做源码侧改名,一个服务一个提交,让 bisect 保持有意义。
  5. 为无法部署的第三方服务生成 Collector transform,并在配置文件里就把它标成临时方案。
  6. 在合并后的树上重跑迁移,确认未映射清单已经清空,或者被显式豁免。
  7. 在同一个 pull request 里更新仪表盘 JSON 和消费它的仪表盘,绝不推到后续工单里。

第七条正是最常被跳过的那条,也正是它造出了那种每一道 CI 检查都是绿的、在生产里却已经错了一个月的迁移。

数字接下来该往哪儿去

迁移只是可观测性升级里枯燥的那一半。有意思的那一半,是名字对了、未映射属性清干净之后,你的 span 长什么样。属性名一旦稳定,同一份 span 数据就开始和那些为结构化遥测而生的工具配合起来,包括 Logfmt 与 JSON 结构化日志桥接,用来处理带着同一套属性词汇的扁平日志行。当你需要确认一个传播的上下文字段熬过了服务跳转,OpenTelemetry W3C traceparent / tracestate / baggage 与 OTLP 头传播验证器会直接查线格式。而当某次改名确实错落在了共享仪表盘上,JSON 差异可视化会指出到底是哪条查询变了。跑完迁移,关掉未映射报告,然后到 elysiatools.com 看更多工具。

1 Comment

Leave a Reply

Your email address will not be published. Required fields are marked *