乌克兰国旗 我们与乌克兰的朋友和同事站在一起。为了支持乌克兰，请访问此页面：访问此页面。

迁移到 OpenTelemetry SDK

Jaeger 客户端/SDK 不再受支持

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

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

对于新应用程序，我们建议使用 OpenTelemetry external link - Jaeger 分布式追踪平台 的 API、SDK 和 instrumentation。自 v1.35 版本以来，Jaeger 后端可以接收来自 OpenTelemetry SDK 的原生 OpenTelemetry Protocol (OTLP) external link - Jaeger 分布式追踪平台 格式的追踪数据。

对于已使用 OpenTracing API 进行 instrumentation 的现有应用程序，我们建议将 Jaeger 客户端替换为相应的 OpenTelemetry SDK 以及 Jaeger 支持的大多数语言中提供的 OpenTracing shim/bridge。

迁移到 OpenTelemetry

OpenTelemetry 项目通过 OpenTracing bridge/shim 发布了一份关于从 OpenTracing API 迁移到 OpenTelemetry SDK 的指南 external link - Jaeger 分布式追踪平台。不同的 OpenTelemetry SDK 可能具有不同的成熟度和功能水平。随着更多信息的出现，我们将继续更新以下内容。

Baggage 支持

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

我们需要你的帮助！

如果您发现任何不准确之处或有可以补充的信息，请在文档仓库 external link - Jaeger 分布式追踪平台中提交 issue 或 PR。如果缺少某些您需要的功能，请在相应的 OpenTelemetry 仓库中提交 ticket 或贡献代码。例如，Jaeger 的远程采样器尚未在每个 OpenTelemetry SDK 中实现，但从 Jaeger 代码库移植它们是一项相当直接的任务。

复制 Jaeger 代码

我们鼓励 OpenTelemetry SDK 作者复制 Jaeger 客户端的相关部分，而不是直接依赖 Jaeger 模块。这就是我们使用宽松的 APL2 许可的原因。复制代码时，遵守许可要求的正确方法是保留版权声明。例如，Jaeger 作者对最初在 Uber 编写的代码也采取了同样的方式。

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

Java

Python

Node.js

Go

C# / .NET

C++

传播格式

OpenTelemetry SDK 支持 Jaeger 的追踪上下文 wire 格式，但该格式已被弃用。建议用户使用 OpenTelemetry SDK 官方支持的 W3C Trace-Context external link - Jaeger 分布式追踪平台 格式。

追踪/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）是“已采样”标志
      • 1 表示追踪已被采样，建议所有下游服务尊重此设置
      • 0 表示追踪未被采样，建议所有下游服务尊重此设置
        • 我们正在考虑一项新功能，允许下游服务在其追踪级别过低时进行向上采样
    • 第 2 位（位掩码 0x02）是“调试”标志
      • 调试标志应仅在已采样标志设置时设置
      • 指示后端尽力不丢弃此追踪
    • 第 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