从OpenTracing迁移

从一开始，向后兼容性一直是OpenTelemetry项目的重点。为了简化迁移过程，OpenTelemetry支持在同一个代码库中同时使用OpenTelemetry和OpenTracing API。这允许使用OpenTelemetry SDK记录OpenTracing的仪表。

为实现这一目标，每个OpenTelemetry SDK都提供了一个OpenTracing shim，它充当OpenTracing API和OpenTelemetry SDK之间的桥梁。请注意，默认情况下，OpenTracing shims是禁用的。

语言版本支持

在使用OpenTracing shim之前，检查项目的语言和运行时组件版本，并根据需要进行更新。下表列出了OpenTracing和OpenTelemetry API的最低语言版本要求。

语言	OpenTracing API	OpenTelemetry API
Go	1.13	1.16
Java	7	8
Python	2.7	3.6
JavaScript	6	8.5
.NET	1.3	1.4
C++	11	11

OpenTelemetry API和SDK通常对于语言版本的要求更高于OpenTracing。

迁移概述

许多代码库目前都使用OpenTracing进行仪表化。这些代码库使用OpenTracing API来仪表化其应用程序代码，并/或者安装OpenTracing插件以仪表化其库和框架。

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

1. 安装OpenTelemetry SDK，移除当前的OpenTracing实现，例如Jaeger客户端。
2. 安装OpenTelemetry仪表库，移除OpenTracing的等效库。
3. 更新仪表板、警报等，以接收新的OpenTelemetry数据。
4. 在编写新的应用程序代码时，使用OpenTelemetry API进行所有新的仪表化。
5. 逐步使用OpenTelemetry API重新仪表化应用程序。无需强制要求从应用程序中删除现有的OpenTracing API调用，它们仍然可以工作。

尽管迁移一个庞大的应用程序可能需要相当大的工作量，但是建议OpenTracing的用户逐步迁移其应用程序代码。这将减轻迁移的负担，并避免破坏可观察性。

下面的步骤提供了一个细致、逐步的过渡到OpenTelemetry的方法。

步骤1：安装OpenTelemetry SDK

在更改任何仪表化之前，确保你可以切换到OpenTelemetry SDK，而不会破坏应用程序当前产生的遥测数据。推荐只进行此步骤，而不同时引入任何新的仪表化，因为这样更容易确定是否存在任何仪表化中断。

1. 使用OpenTelemetry SDK替换当前使用的OpenTracing Tracer实现。例如，如果使用Jaeger，请移除Jaeger客户端并安装等效的OpenTelemetry客户端。
2. 安装OpenTracing Shim。这个shim允许OpenTelemetry SDK消耗OpenTracing仪表。
3. 配置OpenTelemetry SDK使用与OpenTracing客户端相同的协议和格式导出数据。例如，如果以前使用的OpenTracing客户端以Zipkin格式导出追踪数据，请配置OpenTelemetry客户端以相同格式导出。
4. 或者，将OpenTelemetry SDK配置为发出OTLP，并将数据发送到Collector，可以在其中管理以多种格式导出数据。

安装了OpenTelemetry SDK后，确认你可以部署应用程序并仍然接收到基于OpenTracing的遥测。换句话说，确保你的仪表板、警报和其他基于追踪的分析工具仍然正常工作。

步骤2：逐步替换仪表化

安装了OpenTelemetry SDK后，现在可以使用OpenTelemetry API编写所有新的仪表化。除了少数例外情况外，OpenTelemetry和OpenTracing的仪表化将无缝合作（见下文的兼容性限制）。

那么现有的仪表化怎么办呢？没有硬性要求将现有应用程序代码迁移到OpenTelemetry。但是，我们建议从任何OpenTracing的仪表化库（用于仪表化Web框架、HTTP客户端、数据库客户端等的库）迁移到它们的OpenTelemetry等效库。这样做会提高支持性，因为许多OpenTracing库将被弃用，并可能不再进行更新。

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

对于现有的仪表化，建议按照以下步骤进行：

1. 使用OpenTelemetry等效库替换一个OpenTracing的仪表化。
2. 观察这如何改变应用程序所生成的遥测。
3. 创建新的仪表板、警报等来消耗这个新的遥测。在将新的OpenTelemetry库部署到生产环境之前配置好这些仪表板。
4. 可选地，向Collector添加处理规则，将新的遥测转换为旧的遥测。然后配置Collector发出相同遥测的两个版本，创建数据重叠。这样可以让新的仪表板填充自己，同时继续使用旧的仪表板。

兼容性限制

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

语义约定

如前所述，OpenTelemetry对于软件仪表化有一个改进的模型。这意味着OpenTracing仪表化设置的"标签"可能会与OpenTelemetry设置的"属性"不同。换句话说，在替换现有仪表化时，OpenTelemetry生成的数据可能与OpenTracing生成的数据不同。

再次强调：在更改仪表化时，请确保更新依赖于旧数据的所有仪表板、警报等。

Baggage

在OpenTracing中，Baggage是与Span关联的SpanContext对象的一部分。在OpenTelemetry中，上下文和传播是较低级别的概念，Span、Baggage、度量仪表和其他项目都包含在上下文对象中。

由于这个变化，使用OpenTracing API设置的Baggage在OpenTelemetry Propagator中不可用。因此，不推荐在使用Baggage时混合使用OpenTelemetry和OpenTracing API。

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

• 不能通过OpenTelemetry API访问它。
• 不能使用OpenTelemetry传播器注入它。

如果使用Baggage，请建议将所有与Baggage相关的API调用一次性切换到OpenTelemetry。在将这些更改推进到生产环境之前，请检查是否仍然传播了任何关键的Baggage项。

JavaScript中的上下文管理

在JavaScript中，OpenTelemetry API使用常见的上下文管理器，例如Node.js的async_hooks和浏览器的Zones.js。这些上下文管理器使得跟踪仪表化比起每个需要跟踪的方法将span作为参数添加要少侵入性和负担。

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

我们建议将完整的代码路径从OpenTracing迁移到OpenTelemetry作为一个单独的单元，以便一次只使用一个API。

规范和实现细节

关于每个OpenTracing shim的详细信息，请参阅相应的语言特定文档。关于OpenTracing shim的设计细节，请参阅OpenTracing兼容性。