OpenTelemetry 的升级方法
在规模化管理广泛分布的软件时，需要仔细考虑向后兼容性、版本控制和升级。OpenTelemetry 的方法如下所述。如果您计划使用 OpenTelemetry，了解我们如何处理这个问题将非常有帮助。
组件概述
为了促进平稳的升级和长期支持，OpenTelemetry 客户端被分解为几个组件。我们在本文档的其余部分使用以下术语。
包 (Packages) 是代码单元的通用术语，它们通过某种形式的依赖管理相互引用。请注意，每种编程语言都有不同的依赖管理方法，并可能使用不同的术语（如模块或库）来表示此概念。
API 指的是编写 OpenTelemetry 仪器所需的全部接口和常量的软件包集合。API 的实现可以在应用程序启动时注册。如果未注册其他实现，API 默认会注册一个 no-op (空操作) 实现。
SDK 指的是 OpenTelemetry 项目提供的、实现 API 的框架。虽然可以编写替代的 API 实现来处理特殊情况，但我们预计大多数用户在运行 OpenTelemetry 时都会安装 SDK。
插件接口 (Plugin Interfaces) 指的是 SDK 提供的扩展点。这些接口包括控制采样、导出数据以及各种其他生命周期钩子的接口。请注意，这些接口不属于 API，而是属于 SDK。
仪器 (Instrumentation) 指的是任何调用 API 的代码。这包括 OpenTelemetry 项目提供的仪器、第三方仪器，以及应用程序代码和自行本机集成的库。
插件 (Plugins) 指的是实现 SDK 插件接口的任何包。这包括 OpenTelemetry 项目提供的插件以及第三方插件。
插件和仪器之间存在重要区别。插件实现插件接口。仪器调用 API。这种区别与 OpenTelemetry 的升级方法有关。
依赖管理
OpenTelemetry 用户和实现者务必及时更新到最新版本的 OpenTelemetry API。OpenTelemetry 遵循严格的向后兼容性规则。升级到 OpenTelemetry 包的最新次要版本始终是安全的。
应用开发者
建议计划在应用程序中安装 OpenTelemetry SDK 的开发者接受所有次要版本升级。这将确保应用程序始终使用最新的优化和安全补丁进行构建。
同样，我们鼓励应用程序开发者依赖当前主版本 OpenTelemetry API 的所有未来版本。这将确保在升级仪器以利用未来次要版本的新功能时不会发生版本冲突。
库维护者
维护开源库的开发者被鼓励使用 OpenTelemetry API 将仪器直接添加到他们的库代码中。我们将这种方法称为“本机仪器”。
将 OpenTelemetry API 添加为库的依赖项时，非常重要的一点是依赖当前主版本的所有未来版本。
依赖特定次要版本可能会导致版本冲突，因为其他库会利用稍后次要版本中添加的 API 功能。API 的次要版本更新永远不会与现有仪器产生兼容性问题。依赖 API 的未来版本完全安全。
SDK 实现者
官方 OpenTelemetry SDK 的维护者以及替代 SDK 的维护者必须保持其实现与最新版本的 OpenTelemetry API 兼容且及时更新。
当 OpenTelemetry API 发布新的次要版本时，它们将包含新功能。这包括新接口以及当前接口的新方法。SDK 维护者应及时发布实现这些功能的新版本。
如果您认为自己无法继续以这种方式维护实现，我们强烈建议您不要实现替代 SDK。OpenTelemetry 不可避免地会发布新功能，而应用程序开发者和库维护者也将利用这些功能。
OpenTelemetry 升级路径
在详细介绍设计要求之前，先说明一下升级实际如何工作。请注意，所有 OpenTelemetry 组件（API、SDK、插件、仪器）都有单独的版本号。
API 变更
当新功能添加到 OpenTelemetry API 时，会发布 API 的新次要版本。从导入和调用旧版本的现有仪器包的角度来看，这些 API 更改始终是增加性的且向后兼容的。使用所有早期次要版本 API 编写的仪器将继续工作，并且可以在同一应用程序中组合使用，而不会产生依赖冲突。
API 实现者应始终以最新版本的 API 为目标。当发布新版本的 API 时，支持该 API 的 SDK 版本将同步发布。旧版本的 SDK 不支持新版本的 API。
SDK 变更
错误修复、安全补丁和性能改进将作为 SDK 的补丁版本发布。对新 API 版本的支持将作为次要版本发布。新的插件接口将通过 SDK 的次要版本更新发布。
插件接口的破坏性更改将通过弃用处理。不是直接破坏插件接口，而是创建一个新接口，并将现有接口标记为弃用。针对已弃用接口的插件将继续工作，SDK 提供任何缺失功能的默认实现。一年后，该已弃用接口可能会在 SDK 的主版本发布中被移除。
设计要求和说明
这种升级方法解决了两个关键的设计要求，同时最大限度地减少了与遗留代码相关的维护开销。
- API 的调用者永远不会被破坏。
- SDK 的用户可以轻松升级到最新版本。
为现有仪器提供无限期的支持是 OpenTelemetry 的关键特性。预计将有数百万行代码使用 API 编写。这包括附带集成 OpenTelemetry 仪器的共享库。这些库必须能够组合到应用程序中，而不会因 OpenTelemetry 产生依赖冲突。虽然一些仪器将被更新到最新的 API 版本（如 OpenTelemetry 项目提供的），但其他仪器将永远不会被更新。
使用新仪器可能需要用户升级到最新版本的 SDK。如果升级不方便，OpenTelemetry 项目将被迫支持旧版本的 SDK 以及整个仪器生态系统的旧版本。
这最多是一种巨大的维护负担。但是，由于 OpenTelemetry 项目仅控制该生态系统的一部分，因此也是不可行的。OpenTelemetry 不能要求具有本机仪器支持的库支持多个版本的 API。确保应用程序所有者和操作人员可以升级到最新版本的 SDK 可以解决这个问题。
升级 SDK 的主要障碍是过时的插件。如果新版本的 SDK 破坏了现有的插件接口，那么在用户依赖的插件升级之前，任何人都无法升级他们的 SDK。用户可能会陷入他们依赖的仪器需要一个与支持其插件的 SDK 版本不兼容的 API 版本，而其插件又依赖旧版本的 SDK 的困境。
通过遵循插件接口的弃用模式，我们在新 SDK 发布后创建了一个为期一年的窗口，供插件生态系统进行升级。我们相信，这足以让任何积极维护的插件进行升级，并识别和替换已废弃的插件。
通过确保 SDK 可以轻松升级，我们还为应用程序所有者和操作人员提供了一条途径，让他们能够快速使用关键的错误修复和安全补丁，而无需将这些补丁向后移植到大量先前的 SDK 版本。