OpenCensus 兼容性

状态: 稳定，除非另有说明。

OpenTelemetry 项目旨在提供与 OpenCensus 项目的向后兼容性，以帮助迁移已 instrumented 的代码库。

迁移路径

迁移到 OpenTelemetry 时的破坏性更改

从 OpenCensus 迁移到 OpenTelemetry 可能需要对生成的遥测数据进行破坏性更改，因为

• 名称和属性的语义约定不同或新增（例如，grpc.io/server/server_latency vs rpc.server.duration）
• 数据模型差异（例如，OpenCensus 支持 SumOfSquaredDeviations，而 OTLP 不支持）
• Instrumentation API 功能差异（例如，OpenCensus 支持 基于上下文的属性），而 OTel 不支持）
• 等效 OC 和 OTel Exporter 之间的差异（例如，OpenTelemetry Prometheus Exporter 添加了类型和单位后缀；OpenCensus 则不添加）

此迁移路径将大多数破坏性更改集中在安装 Bridge 上。这使用户能够控制引入初始破坏性更改，并使后续的 Instrumentation 迁移（包括第三方库的迁移）不会产生破坏性。

迁移计划

从 OpenCensus Agent 和 Protocol 迁移

从部署 OC agent 和 OC 协议开始，通过以下方式迁移：

1. 部署带有 OpenCensus 和 OTLP 接收器以及等效处理器和导出的 OpenTelemetry Collector。
2. 破坏性更改：对于每个发送 OC 协议的工作负载，更改为发送到 OpenTelemetry Collector 的 OpenCensus 接收器。
3. 移除 OC Agent 的部署。
4. 对于每个工作负载，按照以下指南将应用程序从 OpenCensus 迁移到 OpenTelemetry，并使用 OTLP Exporter。

迁移使用 Bridge 的应用程序

从一个完全使用 OpenCensus Instrumentation 进行 trace 和 metrics 的应用程序开始，可以通过以下方式迁移：

1. 迁移 Exporter（SDK）
   1. 安装 OpenTelemetry SDK，并带有等效的 Exporter。
      1. 如果使用 OpenCensus Exporter，则切换到使用 OTLP Exporter。
   2. 安装等效的 OpenTelemetry Resource Detectors。
   3. 安装 OpenTelemetry W3c TraceContext Propagator，这是 OpenCensus TextFormat Propagator 的等效项。
   4. 破坏性更改：安装 metrics 和 trace Bridge。
   5. 移除 OpenCensus Exporter 的初始化。
2. 迁移 Instrumentation（API）
   1. 破坏性更改：对于 OpenCensus Instrumentation 包，迁移到 OpenTelemetry 的等效项。
      1. 如果迁移 gRPC，则启用 BinaryPropagation Propagator（如果语言支持）。否则，在 OpenTelemetry gRPC Instrumentation 上启用 OpenCensus BinaryPropagation。
   2. 对于外部依赖项，等待其迁移到 OpenTelemetry，然后更新该依赖项。
   3. 对于应用程序本身的 Instrumentation，请按照下面的“库”指南进行迁移。
3. 清理：移除 metrics 和 trace Bridge。

迁移使用 OC Instrumentation 的库

就地迁移

希望进行简单迁移的库可以选择就地替换 Instrumentation。

从使用 OpenCensus Instrumentation 的库开始。

1. 向用户宣布库从 OpenCensus 过渡到 OpenTelemetry，并建议用户采用 OC Bridge。
2. 将单元测试更改为使用 OC Bridge，并使用 OpenTelemetry 单元测试框架。
3. 在通知期后，逐行将 Instrumentation 迁移到 OpenTelemetry。对于流行库，通知期应足够长。
4. 从单元测试中移除 OC Bridge。

通过配置迁移

希望尽早添加原生 OpenTelemetry Instrumentation 的库，和/或希望为 OpenCensus 提供扩展支持的库，可以选择为用户提供使用 OpenCensus Instrumentation *或* OpenTelemetry Instrumentation 的选项。

从使用 OpenCensus Instrumentation 的库开始。

1. 将单元测试更改为使用 OC Bridge，并使用 OpenTelemetry 单元测试框架。
2. 添加允许用户启用 OpenTelemetry Instrumentation 并禁用 OpenCensus Instrumentation 的配置。
3. 添加由配置控制、并使用相同单元测试集进行测试的 OpenTelemetry Instrumentation。
4. 在通知期后，默认切换到使用 OpenTelemetry Instrumentation。
5. 在弃用期后，移除使用 OpenCensus Instrumentation 的选项。

Trace Bridge

Trace Bridge 提供了一个 Shim 层，它使用 OpenTelemetry Trace API 来实现 OpenCensus Trace API。此层 **不得** 依赖于 OpenTelemetry SDK 的实现细节。

更具体地说，其目的是允许使用 OpenTelemetry 记录 OpenCensus Instrumentation。此 Shim 层 **不得** 公开任何上游 OpenTelemetry API。

OpenCensus Shim 和 OpenTelemetry API/SDK 预计将在运行的服务中同时被使用，以方便从前者迁移到后者。预计应用程序所有者将通过 Shim 开始向 OpenTelemetry 迁移，并通过 OpenTelemetry 添加新的遥测信息。Libraries 和集成也将逐渐迁移到 opentelemetry，直到 Shim 不再需要。

例如，今天的应用程序可能具有以下类型的 Trace：

|-- Application - Configured OpenCensus --------------------------------- |
    |--  gRPC -> Using OpenCensus to generate Trace A  --------- |
      |--  Application -> Using OpenCensus to generate a sub Trace B-- |

在这种情况下，应用程序应该能够更新其外层到 OpenTelemetry，而无需等待所有下游依赖项都更新到 OpenTelemetry（或处理其中的不兼容性）。应用程序也不需要重写其自身的任何 Instrumentation。

|-- Application - Configured Otel w/ OpenCensus Shim ------------------- |
    |--  gRPC -> Using OpenCensus to generate Trace A  --------- |
      |--  Application -> Using OpenCensus to generate a sub Trace B-- |

接下来，应用程序可以分块地更新其自身的 Instrumentation：

|-- Application - Configured Otel w/ OpenCensus Shim ---------------------- |
    |--  gRPC -> Using OpenCensus to generate Trace A  --------- |
      |--  Application -> Using OpenTelemetry to generate a sub Trace B-- |

这个 Otel -> OpenCensus -> Otel tracing 层可以被认为是“OpenTelemetry 三明治”问题，也是此规范的关键驱动因素。

最后，应用程序将把所有 OpenCensus 的使用都更新为 OpenTelemetry。

|-- Application - Configured Otel standalone ----------------------------- |
    |--  gRPC -> Using Otel to generate Trace A  --------- |
      |--  Application -> Using OpenTelemetry to generate a sub Trace B-- |

要求

OpenTelemetry <-> OpenCensus Trace Bridge 具有以下要求：

• OpenCensus 对 OpenTelemetry 没有硬性依赖。
• 对 OpenCensus 的实现更改最少。
• 易于用户使用，最好是无需更改其代码。
• 在应用程序和库之间维护父子 Span 关系。
• 在应用程序和库之间维护 Span 链接关系。
• 此组件 **必须** 是一个可选依赖项。

在 OpenCensus 中创建 Span

当 Shim 处于就位状态时，所有 OpenCensus Span **必须** 通过 OpenTelemetry Tracer 发送，如 OpenTelemetry API 所指定。

对于支持依赖项发现和自动注入的语言，此机制对用户应该是无缝的。

Span 的方法

OpenCensus 中所有指定的 Spec 方法都将委托给底层的 OpenTelemetry Span。

资源

注意：在 OpenCensus 的“API”部分似乎无法使用 Resource。

已知不兼容项

下面列出了 OpenTelemetry 和 OpenCensus 规范之间的已知不兼容项。利用 OpenCensus 未指定行为但 **在 OpenTelemetry 中** 被指定为不兼容的应用程序，不符合使用 OpenCensus <-> OpenTelemetry Bridge 的资格。

1. 在 OpenCensus 中，对于何时可以将父 Span 指定给子 Span，没有规范。OpenTelemetry 指定 父 Span 必须在 Span 创建时指定。这导致 OpenCensus 允许在初始化后灵活指定父 Span 的 API 出现一些问题。
2. 在 Span 创建后将其链接添加到 Span。这在 OpenTelemetry 中不受支持，因此，在创建后添加了链接的 OpenCensus Span 将被映射到没有链接的 OpenTelemetry Span。
3. OpenTelemetry 指定 Sampler **附加到整个 Trace Provider**，而 OpenCensus 允许为每个 Span 自定义 Sampler。
4. OpenCensus 和 OpenTelemetry 中的 TraceFlags 都只指定了单个 sampled 标志（OpenTelemetry，OpenCensus）。某些 OpenCensus API 除了“sampled”之外，还支持“debug”和“defer” tracing 标志。在这种情况下，OpenCensus Bridge 将尽最大努力支持和翻译未指定的标志到最接近的 OpenTelemetry 等效项。

OpenCensus 二进制上下文传播

Shim 将提供一个 OpenCensus BinaryPropogator 实现，该实现将 OpenCensus 二进制 trace 上下文格式 映射到 OpenTelemetry SpanContext。

此适配器 **必须** 提供 OpenCensus BinaryPropogator 的实现，以使用 OpenTelemetry 的上下文编写 OpenCensus 二进制格式。如果适用，此实现可以从 OpenCensus 中提取。

如果可能，BinaryPropagator **必须** 是一个 TextMapPropagator。否则，BinaryPropagator **必须** 是一个库，该库预计会被 OpenTelemetry gRPC Instrumentation 使用。这些语言中的 gRPC Instrumentation **不应** 默认启用 BinaryPropagator，但 **应** 提供配置以允许用户启用它。

Metrics / Stats

OpenTelemetry 将提供一个 OpenCensus-Metrics-Shim 组件，该组件实现 OpenTelemetry 的 MetricProducer 接口。当调用 Produce() 时，Shim 会收集 OpenCensus 全局状态中的 Metrics，将 Metrics 转换为 OpenTelemetry Metrics Batch，然后返回。

要求

• 此组件 **必须** 是一个可选依赖项。
• **必须** 不要求 OpenTelemetry 包含在 OpenCensus API 发行版中。
• 运行时 **应** 不要求 OpenCensus 依赖于 OpenTelemetry。
• **必须** 要求对 OpenCensus 的更改很少或没有更改。
• **必须** 与 push 和 pull Exporter 兼容。
• **必须** 支持 Gauges、Counters、Cumulative Histograms 和 Summaries。
• **不要求** 支持 Gauge Histograms。
• **必须** 在提供将 Span Context 记录到 Exemplar 中的语言中支持 Exemplar Span Context。

资源

Shim **必须** 丢弃附加到 OpenCensus Metrics 的 Resource，并插入初始化期间提供的 Resource，或回退到默认的 OpenTelemetry Resource。

Instrumentation Scope

Shim **必须** 添加一个识别 Shim 的 instrumentation scope 名称和版本。

用法

Shim 可以作为选项传递给 OpenTelemetry MetricReader 来配置 OpenTelemetry SDK。这使得 Bridge 能够与 push 和 pull Metrics Exporter 一起工作。

已知不兼容项

• OpenTelemetry 不支持 OpenCensus 的 GaugeHistogram 类型；使用 Bridge 时 **必须** 丢弃这些 Metrics。
• OpenTelemetry 目前不支持基于上下文的属性（Tags）。
• OpenTelemetry 不支持 OpenCensus 的 SumOfSquaredDeviation 字段；使用 Bridge 时 **必须** 丢弃此字段。