从 OpenTracing 迁移

从一开始，OpenTelemetry 项目就优先考虑了与 OpenTracing 的向后兼容性。为了简化迁移，OpenTelemetry 支持在同一代码库中同时使用 OpenTelemetry 和 OpenTracing API。这允许使用 OpenTelemetry SDK 记录 OpenTracing instrumentation。

为此，每个 OpenTelemetry SDK 都提供了一个 **OpenTracing 适配器**，它充当 OpenTracing API 和 OpenTelemetry SDK 之间的桥梁。请注意，OpenTracing 适配器默认是禁用的。

语言版本支持

在使用 OpenTracing 适配器之前，请检查您项目的语言和运行时组件版本，并在必要时进行更新。下表列出了 OpenTracing 和 OpenTelemetry API 的最低 **语言** 版本。

请注意，OpenTelemetry API 和 SDK 通常比其 OpenTracing 对应项具有更高的语言版本要求。

迁移概述

许多代码库目前都使用 OpenTracing 进行 instrumentation。这些代码库使用 OpenTracing API 来 instrument 应用程序代码和/或安装 OpenTracing 插件来 instrument 库和框架。

迁移到 OpenTelemetry 的一般方法可以总结如下：

1. 安装 OpenTelemetry SDK，并移除当前的 OpenTracing 实现 – 例如，Jaeger 客户端。
2. 安装 OpenTelemetry instrumentation 库，并移除 OpenTracing 的对应库。
3. 更新您的仪表板、警报等，以使用新的 OpenTelemetry 数据。
4. 在编写新的应用程序代码时，请使用 OpenTelemetry API 编写所有新的 instrumentation。
5. 逐步使用 OpenTelemetry API 重新 instrument 您的应用程序。现有 OpenTracing API 调用没有硬性要求必须移除，它们将继续工作。

虽然迁移大型应用程序可能需要大量的努力，但如上所述，我们建议 OpenTracing 用户逐步迁移他们的应用程序代码。这将减轻迁移负担，并有助于避免可观测性中断。

下面的步骤提供了一种谨慎的、增量的方法来过渡到 OpenTelemetry。

步骤 1：安装 OpenTelemetry SDK

在更改任何 instrumentation 之前，请确保您可以切换到 OpenTelemetry SDK 而不会导致应用程序当前发出的遥测数据出现任何中断。建议单独执行此步骤 – 而不是同时引入任何新的 instrumentation – 因为这使得确定是否存在任何中断类型更容易。

1. 用 OpenTelemetry SDK 替换您当前使用的 OpenTracing Tracer 实现。例如，如果您使用的是 Jaeger，请移除 Jaeger 客户端并安装相应的 OpenTelemetry 客户端。
2. 安装 OpenTracing 适配器。此适配器允许 OpenTelemetry SDK 使用 OpenTracing instrumentation。
3. 将 OpenTelemetry SDK 配置为使用 OpenTracing 客户端以前使用的相同协议和格式导出数据。例如，如果您使用的 OpenTracing 客户端以 Zipkin 格式导出跟踪数据，请将 OpenTelemetry 客户端配置为执行相同的操作。
4. 或者，将 OpenTelemetry SDK 配置为发出 OTLP，并将数据发送到 Collector，在那里您可以管理以多种格式导出数据。

一旦安装了 OpenTelemetry SDK，请确认您可以部署您的应用程序并仍然接收相同的基于 OpenTracing 的遥测数据。换句话说，确认您的仪表板、警报和其他基于跟踪的分析工具仍然正常工作。

步骤 2：逐步替换 instrumentation

安装 OpenTelemetry SDK 后，现在可以使用 OpenTelemetry API 编写所有新的 instrumentation。除少数例外，OpenTelemetry 和 OpenTracing instrumentation 将无缝协同工作（参见下面的 兼容性限制）。

现有的 instrumentation 怎么办？现有的应用程序代码没有硬性要求必须迁移到 OpenTelemetry。但是，我们确实建议从任何 OpenTracing instrumentation 库 – 用于 instrument Web 框架、HTTP 客户端、数据库客户端等的库 – 迁移到相应的 OpenTelemetry 库。这将改善支持，因为许多 OpenTracing 库将被淘汰，可能不再更新。

需要注意的是，在切换到 OpenTelemetry instrumentation 库时，产生的数据将会发生变化。OpenTelemetry 拥有一个改进的软件 instrument 模型（我们称之为“语义约定”）。在许多情况下，OpenTelemetry 会产生更好、更全面的跟踪数据。但是，“更好”也意味着“不同”。这意味着基于旧 OpenTracing instrumentation 库的现有仪表板、警报等在替换这些库后可能不再工作。

对于现有的 instrumentation，建议：

1. 将一个 OpenTracing instrumentation 替换为其 OpenTelemetry 对应项。
2. 观察这如何改变您的应用程序产生的数据。
3. 创建使用此新数据的新仪表板、警报等。在将新的 OpenTelemetry 库部署到生产环境之前设置这些仪表板。
4. 或者，将处理规则添加到 Collector，将新数据转换回旧数据。然后可以将 Collector 配置为发出相同数据的两个版本，从而创建数据重叠。这允许在继续使用旧仪表板的同时填充新仪表板。

兼容性限制

在本节中，我们将描述除前面提到的 语言版本约束 之外的兼容性限制。

语义约定

如上所述，OpenTelemetry 拥有一个改进的软件 instrumentation 模型。这意味着 OpenTracing instrumentation 设置的“标签”可能与 OpenTelemetry 设置的“属性”不同。换句话说，在替换现有 instrumentation 时，OpenTelemetry 产生的数据可能与 OpenTracing 产生的数据不同。

再次说明，为了清晰起见：更改 instrumentation 时，请务必同时更新依赖旧数据的任何仪表板、警报等。

Baggage

在 OpenTracing 中，baggage 随 SpanContext 对象一起携带，该对象与 Span 相关联。在 OpenTelemetry 中，上下文和传播是更底层的概念——span、baggage、metrics instrument 和其他项目都包含在上下文对象中。

由于此更改，OpenTracing API 设置的 baggage 对 OpenTelemetry Propagators 不可用。因此，不建议在使用 baggage 时混合使用 OpenTelemetry 和 OpenTracing API。

具体来说，当使用 OpenTracing API 设置 baggage 时：

• OpenTelemetry API 无法访问它。
• OpenTelemetry Propagators 不会注入它。

如果您正在使用 baggage，建议同时将所有与 baggage 相关的 API 调用切换到 OpenTelemetry。在将这些更改部署到生产环境之前，请务必检查关键 baggage 项是否仍在传播。

JavaScript 中的上下文管理

在 JavaScript 中，OpenTelemetry API 利用了常用的上下文管理器，例如 Node.js 的 async_hooks 和浏览器的 Zones.js。与将 span 添加为需要跟踪的每个方法的参数相比，这些上下文管理器使得 tracing instrumentation 成为一项侵入性更小、负担更小的任务。

然而，OpenTracing API 早于这些上下文管理器的普遍使用。传递当前活动 span 作为参数的 OpenTracing 代码，在与将活动 span 存储在上下文管理器中的 OpenTelemetry 代码混合使用时可能会产生问题。在同一 trace 中同时使用这两种方法可能会导致 span 损坏或不匹配，因此不推荐这样做。

与其在同一 trace 中混合使用这两种 API，我们建议您将完整的代码路径作为一个整体从 OpenTracing 迁移到 OpenTelemetry，这样一次只使用一种 API。

规范和实现细节

有关每个 OpenTracing 适配器如何工作的信息，请参阅相应的语言特定文档。有关 OpenTracing 适配器设计的信息，请参阅 OpenTracing Compatibility。