迁移到 OpenTelemetry SDK

Jaeger 客户端/SDK 不再受支持

Jaeger 客户端已于 2022 年退役。请使用 OpenTelemetry SDK。

Jaeger 客户端多年来一直忠实地服务于我们的社区。我们开创了许多新功能，例如远程控制采样器和按操作/自适应采样，这些对于大型组织分布式追踪部署的成功至关重要。然而，现在 OpenTelemetry 的更大社区在功能对等性方面已经赶上了 Jaeger 客户端，并且完全支持将数据导出到 Jaeger，我们认为现在是时候**停用 Jaeger 的原生客户端并将精力重新集中到 OpenTelemetry SDK 上**了。

对于新应用，我们建议使用 OpenTelemetry API、SDK 和 Instrumentation。自 v1.35 版本起，Jaeger 后端可以接收来自 OpenTelemetry SDK 的原生 OpenTelemetry 协议 (OTLP) 追踪数据。

对于已经使用 OpenTracing API 进行 instrumented 的现有应用，我们建议用相应的 OpenTelemetry SDK 和 Jaeger 支持的大多数语言中可用的 OpenTracing shim/bridge 替换 Jaeger 客户端。

迁移到 OpenTelemetry

OpenTelemetry 项目发布了一份迁移指南，指导如何通过 OpenTracing bridges/shims 从 OpenTracing API 迁移到 OpenTelemetry SDK。不同的 OpenTelemetry SDK 可能具有不同的成熟度和功能水平。我们将随着更多信息的可用性而持续更新以下内容。

Baggage 支持

OpenTelemetry 实现 baggage 传播的方式与 OpenTracing 不同，它们并非完全等同。在 OpenTelemetry 中，context 层位于追踪 API 下方，并依赖于不可变上下文对象，而 OpenTracing 中的 baggage 则存储在一个可变的 span 中（有时在启动子 span 时可能导致复杂的竞态条件）。

我们需要您的帮助！

如果您发现不准确之处或有可以补充的信息，请向文档仓库提交 issue 或 PR。如果缺少某些您需要的功能，请在相应的 OpenTelemetry 仓库中提交工单或做出贡献。例如，Jaeger 的远程采样器尚未在所有 OpenTelemetry SDK 中实现，但将其从 Jaeger 代码库移植过来是一个相当直接的任务。

复制 Jaeger 代码

// Copyright (c) 2019 The Jaeger Authors.
// Copyright (c) 2017 Uber Technologies, Inc.
// ... <rest of Apache notice> ...

Java

OpenTelemetry SDK: https://github.com/open-telemetry/opentelemetry-java
- 远程采样: sdk-extensions/jaeger-remote-sampler
- 内部 SDK 指标：不适用
OpenTracing 桥接: opentracing-shim
- 迁移指南: “从 Jaeger 客户端迁移到 OpenTelemetry SDK”

Python

OpenTelemetry SDK: https://github.com/open-telemetry/opentelemetry-python
- 远程采样：？
- 内部 SDK 指标：不适用
OpenTracing 桥接: opentelemetry-opentracing-shim
- 迁移指南：可在 shim 的 README 中找到

Node.js

OpenTelemetry SDK: https://github.com/open-telemetry/opentelemetry-js
- 远程采样：？
- 内部 SDK 指标：不适用
OpenTracing 桥接: opentelemetry-shim-opentracing
- 迁移指南：可在 shim 的 README 和相应的 readthedocs 中找到

Go

OpenTelemetry SDK: https://github.com/open-telemetry/opentelemetry-go
- 远程采样: https://github.com/open-telemetry/opentelemetry-go-contrib/pull/936
- 内部 SDK 指标：不适用
OpenTracing 桥接: bridge/opentracing
- 迁移指南：？

C# / .NET

OpenTelemetry SDK: https://github.com/open-telemetry/opentelemetry-dotnet
- 远程采样：？
- 内部 SDK 指标：不适用
OpenTracing 桥接: OpenTelemetry.Shims.OpenTracing
- 迁移指南：可在 shim 的 README 中找到，但内容非常简略

C++

OpenTelemetry SDK: https://github.com/open-telemetry/opentelemetry-cpp
- 远程采样：？
- 内部 SDK 指标：不适用
OpenTracing 桥接：不适用
- 迁移指南：不适用

传播格式

Jaeger 的 trace context 有线格式受 OpenTelemetry SDK 支持，但已弃用。建议用户使用 OpenTelemetry SDK 官方支持的 W3C Trace-Context 格式。

追踪/Span 标识

键

uber-trace-id

HTTP 中不区分大小写
在保留头大小写的协议中为小写

值

{trace-id}:{span-id}:{parent-span-id}:{flags}

{trace-id}
- Base16 格式的 64 位或 128 位随机数
- 可以是变长，较短的值在左侧用 0 填充
  - 接收方必须接受短于 32 个字符的十六进制字符串并在左侧用 0 填充
  - 发送方应生成长度恰好为 16 或 32 个字符的十六进制字符串
- 某些语言的客户端支持 128 位，迁移待定
- 值为 0 无效
{span-id}
- Base16 格式的 64 位随机数
- 可以是变长，较短的值在左侧用 0 填充
  - 接收方必须接受短于 16 个字符的十六进制字符串并在左侧用 0 填充
  - 发送方应生成长度恰好为 16 个字符的十六进制字符串
- 值为 0 无效
{parent-span-id}
- Base16 格式的 64 位值，表示父 span ID
- 已弃用，大多数 Jaeger 客户端在接收端会忽略，但在发送端仍会包含它
- 值为 0 有效，表示“根 span”（未被忽略时）
{flags}
- 一个字节的位图，表示为一个或两个十六进制数字（可以省略前导零）
- 位 1（最右边，最低有效位，位掩码 0x01）是“sampled”标志
  - 1 表示追踪已采样，并建议所有下游服务遵守此规则
  - 0 表示追踪未采样，并建议所有下游服务遵守此规则
    - 我们正在考虑一项新功能，允许下游服务在发现其追踪级别过低时进行上采样
- 位 2（位掩码 0x02）是“debug”标志
  - 调试标志应仅在采样标志设置时设置
  - 指示后端尽力不丢弃此追踪
- 位 3（位掩码 0x04）未使用
- 位 4（位掩码 0x08）是“firehose”标志
  - 标记为“firehose”的 Span 不会在存储中被索引
  - 追踪只能通过追踪 ID 检索（通常可从其他来源（如日志）获取）
- 其他位未使用

Baggage

键：uberctx-{baggage-key}
值：{baggage-value} 字符串形式（参见下面的值编码）
限制：由于 HTTP 头不保留大小写，Jaeger 建议 baggage 键使用小写连字符命名法 (lowercase-kebab-case)，例如 my-baggage-key-1。

示例：以下代码序列

span.SetBaggageItem("key1", "value1")
span.SetBaggageItem("key2", "value2")

将产生以下 HTTP 头

uberctx-key1: value1
uberctx-key2: value2

值编码

OpenTracing 定义了两种纯文本头格式：HTTP_HEADERS 和 TEXT_MAP。前者是为了处理 HTTP 协议对头上下文施加的限制而引入的，而后者不施加任何限制，例如，它可以与 Kafka Record Headers 一起使用。这两种格式在 Jaeger SDK 中的主要区别是，当使用 HTTP_HEADERS 传播格式时，baggage 值会被进行 URL 编码。

示例：当使用 HTTP_HEADERS 传播格式时，以下代码序列

span.SetBaggageItem("key1", "value 1 / blah")

将产生以下 HTTP 头

uberctx-key1: value%201%20%2F%20blah