OpenTelemetry OTTL v1 稳定后兼容性承诺覆盖什么

OpenTelemetry Transformation Language（OTTL）从 opentelemetry-collector-contrib v0.164.0 起进入 v1。真正值得关注的不是“多了一个版本号”，而是稳定承诺有明确范围：已经写进语言参考的语法、标准函数集合，以及构建在 OTTL 之上的稳定 Go API，面向 1.x 保持向后兼容；实验函数和仍在 0.x 模块中的能力不在这张保护网里。

官方地址：https://opentelemetry.io/blog/2026/ottl-v1/

升级时可以继续依赖稳定 OTTL，但不能把 xottl、lambda、xprofile 或实验性 Go API 当成同样稳定的接口。排查重点应放在“语句是否属于冻结语法、函数是否已进入标准集合、旧 gate 是否仍存在”这三件事上。

先划清 OTTL v1 的稳定边界

OTTL v1 的兼容承诺覆盖三类对象。第一类是语言语法，包括路径、字面量、运算符、函数调用和 where 子句；第二类是标准函数集合，已有函数不会在 1.x 中被移除，已有签名也不会以不兼容方式改变；第三类是构建自定义组件时使用的稳定 Go API。

这意味着，一条语句如果能在某个 1.x 版本解析，后续 1.x 版本仍应能解析，并保持相同的语义。这里的“兼容”不是说以后永远不会新增能力：小版本仍可以增加新语法，但不能删除或改变既有语法的含义。

因此，看到“OTTL 稳定”时，先问自己使用的是哪一层：只写标准 OTTL 语句，通常可以按 1.x 兼容性规划；如果调用了实验函数或自定义扩展，则必须继续看模块版本和 feature gate。

实验能力为什么不能按 v1 处理

为了避免把每个新函数一加入标准集合就永久背负兼容成本，OTTL 的新能力先放在实验区域。实验函数位于 xottl 模块，模块仍是 0.x；使用它们时通常需要打开 pkg.ottl.functions.enableExperimental feature gate。实验能力可能调整参数、改变行为，甚至在后续版本消失。

lambda 驱动的 Filter、MapEach、MapKeys、Any、All、Find、Reduce 和 When 也仍属于实验范围，需要单独的 ottl.functions.enableLambda gate。profiles 支持则位于单独的 xprofile 模块，实验性 Go API（例如 SliceGetter）同样不应被当成稳定扩展点。

判断标准很简单：不要只看语句“能不能解析”，还要记录它依赖的函数模块、feature gate 和自定义 API。解析成功只能证明当前组合可用，不能自动推出跨版本兼容。

升级 contrib v0.164.0 要查哪些旧配置

v1 发布前，项目已经清理了不打算带入 1.x 的旧内容。升级时需要重点查看从当前版本到 v0.164.0 之间的 contrib changelog，不能只把镜像标签替换后观察 Collector 是否启动。

官方公告列出的直接影响包括：长期弃用的 Base64Decode 和旧 profile 函数被移除；已经达到稳定状态的 ottl.PanicDuplicateName 与 ottl.contexts.enableOTelColContext feature gate 被移除；ottl.set.allowNil gate 也在 v0.164.0 中删除。如果配置仍传递这些 gate，应该先清理，再处理其它语句差异。

# 升级前只保留仍有用途的实验开关，已移除的旧 gate 不要继续传递
feature_gates:
  - pkg.ottl.functions.enableExperimental
  # 只有使用 lambda 函数时才打开下面这一项
  # - ottl.functions.enableLambda

上面的配置只是排查示意，是否启用实验能力仍取决于实际语句。稳定 OTTL 不需要为了“证明 v1”额外打开实验开关。

用四层证据判断兼容性

遇到升级后报错或行为变化，可以按四层检查，不要把所有问题都归结为“OTTL v1 不兼容”。

1. 语句层：确认使用的路径、字面量、运算符、函数调用和 where 写法是否属于语言参考中的稳定语法。
2. 函数层：把每个函数标记为标准集合、实验集合或已删除函数；如果属于实验集合，就同时记录模块和 gate。
3. 组件层：确认实际使用 OTTL 的 processor、connector 或 exporter 是否随 contrib 版本一起升级，并阅读跨版本 changelog。
4. Go API 层：如果维护了自定义组件，检查是否只调用稳定 API；落在 xottl 的实验 API 不能享受同样的 1.x 承诺。

证据也要分开记录：解析错误通常指向语句或函数层，未知 gate 指向升级清理项，自定义组件编译错误则更可能落在 Go API 或模块版本层。这样处理比直接回滚整个 Collector 更容易定位。

把升级检查固化成团队清单

在合并升级变更前，可以保留一份很短的复查记录：

• 列出所有 OTTL 语句，并标记是否只使用稳定语法与标准函数。
• 列出每一个实验函数、lambda、profile 或实验 Go API 的模块与 feature gate。
• 对照当前版本到 v0.164.0 的 changelog，删除旧函数和已移除 gate。
• 为自定义组件单独记录稳定 API 与实验 API，避免编译依赖被配置文件掩盖。
• 保留升级前配置和回滚方式，再观察语句解析、信号处理和导出结果。

结论是：OTTL v1 给稳定语法、标准函数和稳定 Go API 建立了清晰的 1.x 兼容预期，但它没有把所有 OTTL 相关能力一次性变成稳定接口。把稳定区与实验区分开，升级时再补一遍 changelog 和 gate 检查，才是这次版本变化最实用的落地方式。

常见问题

OTTL v1 是否保证所有新函数永久不变？

不是。只有进入标准函数集合的函数才纳入 1.x 兼容承诺；新函数通常先在 xottl 中实验。

使用实验函数是不是一定要自定义构建 Collector？

官方公告说明 contrib 中相关组件会注册实验函数，通常通过匹配的 feature gate 开启，不等于必须自定义构建；但仍要按当前版本文档确认开关名称。

旧 feature gate 还留在配置里会怎样？

如果 gate 已被移除，升级后的 Collector 可能在启动参数或配置解析阶段报错。应先从目标版本 changelog 确认状态，再删除无效参数。

参考入口

OpenTelemetry 官方公告：https://opentelemetry.io/blog/2026/ottl-v1/