烏克蘭國旗 我們與在烏克蘭的朋友和同事們站在一起。為了在他們有需要時支持烏克蘭，請瀏覽此頁面。

用戶端函式庫

版本  1.62 最新

另請參閱

Jaeger 用戶端已停用。請使用 OpenTelemetry SDK。

淘汰 Jaeger 用戶端

Jaeger 用戶端已忠實地為我們的社群服務多年。我們率先推出了許多新功能，例如遠端控制的取樣器和每個操作/自適應取樣，這些功能對於大型組織的分散式追蹤部署的成功至關重要。然而，既然 OpenTelemetry 中更大的社群在功能對等性方面已經趕上了 Jaeger 用戶端，並且完全支援將資料匯出到 Jaeger，我們認為是時候停止使用 Jaeger 的原生用戶端，並將精力重新集中在 OpenTelemetry SDK 上。

對於新的應用程式，我們建議使用 OpenTelemetry 外部連結 API、SDK 和檢測。自 v1.35 起，Jaeger 後端可以使用其原生的 OpenTelemetry 協定 (OTLP) 外部連結 格式接收來自 OpenTelemetry SDK 的追蹤資料。

對於已經使用 OpenTracing API 檢測的現有應用程式，我們建議使用對應的 OpenTelemetry SDK 和 Jaeger 支援的大多數語言中提供的 OpenTracing shim/bridge 來取代 Jaeger 用戶端。

時程

我們計畫在 2021 年底之前繼續接受提取要求並發布 Jaeger 用戶端的新版本。在 2022 年 1 月，我們將進入為期 6 個月的程式碼凍結期，在此期間，我們將不再接受包含新功能的提取要求，但與安全性相關的修復除外。在那之後，我們將封存用戶端函式庫儲存庫，並且將不再接受新的變更。

移轉至 OpenTelemetry

OpenTelemetry 專案發布了透過 OpenTracing 橋接/shim 從 OpenTracing API 移轉至 OpenTelemetry SDK 的移轉指南 外部連結。不同的 OpenTelemetry SDK 中可能會有不同的成熟度和功能等級。隨著更多資訊可用，我們將持續更新以下資訊。

Baggage 支援

OpenTelemetry 以不同於 OpenTracing 的方式實作 baggage 傳播，而且它們並不完全等效。在 OpenTelemetry 中，context 層位於追蹤 API 的下方，並依賴不可變的 context 物件，而 OpenTracing 中的 baggage 則儲存在可變的 span 中（有時可能會在啟動子 span 時導致棘手的競爭條件）。

我們需要您的協助！

如果您發現任何不準確之處或有可以新增的資訊，請在文件儲存庫 外部連結中開啟問題或 PR。如果缺少某些功能且您需要它們，請在各自的 OpenTelemetry 儲存庫中開啟票證或做出貢獻。例如，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++

簡介

所有 Jaeger 客戶端函式庫都支援 OpenTracing API 外部連結。 以下資源提供了更多關於使用 OpenTracing 檢測應用程式的資訊

本頁其餘部分包含有關在已使用 OpenTracing API 進行檢測的應用程式中設定和實例化 Jaeger 追蹤器的資訊。

術語

我們在本文件中交替使用用戶端函式庫、檢測函式庫和追蹤器等詞彙。

支援的函式庫

以下用戶端函式庫是官方支援的

語言GitHub 儲存庫
Gojaegertracing/jaeger-client-go
Javajaegertracing/jaeger-client-java
Node.jsjaegertracing/jaeger-client-node
Pythonjaegertracing/jaeger-client-python
C++jaegertracing/jaeger-client-cpp
C#jaegertracing/jaeger-client-csharp

其他語言的函式庫目前正在開發中，請參閱問題 #366 外部連結。

初始化 Jaeger 追蹤器

每個語言的初始化語法略有不同，請參閱各自儲存庫中的 README。一般模式是不顯式建立追蹤器，而是使用 Configuration 類別來執行此操作。Configuration 允許更簡單地參數化追蹤器，例如變更預設取樣器或 Jaeger 代理程式的位置。

追蹤器內部

取樣

請參閱架構 | 取樣。

回報器

Jaeger 追蹤器使用回報器來處理已完成的 span。通常，Jaeger 函式庫會隨附以下回報器

  • NullReporter 不會對 span 執行任何操作。它在單元測試中很有用。
  • LoggingReporter 只會記錄 span 已完成的事實，通常是透過列印追蹤和 span ID 以及作業名稱。
  • CompositeReporter 採用其他回報器的清單，並逐一叫用它們。
  • RemoteReporter (預設) 會在記憶體中緩衝一定數量的已完成 span，並使用傳送器將一批 span 以異步方式傳送到 Jaeger 後端。傳送器負責將 span 序列化為線路格式 (例如 Thrift 或 JSON)，並與後端元件 (例如透過 UDP 或 HTTP) 通訊。

EMSGSIZE 和 UDP 緩衝區限制

預設情況下，Jaeger 函式庫會使用 UDP 傳送器將已完成的 span 回報給 jaeger-agent 精靈。預設最大封包大小為 65,000 個位元組，透過迴路介面連線到代理程式時，可以不用分段傳輸。然而，某些作業系統 (尤其是 MacOS) 會限制 UDP 封包的最大緩衝區大小，如 此 GitHub 問題 外部連結 中提出的問題。如果您遇到 EMSGSIZE 錯誤的問題，請考慮提高核心中的限制 (請參閱問題中的範例)。您也可以設定用戶端函式庫以使用較小的最大封包大小，但如果您有大型 span，這可能會導致問題，例如，如果您記錄大量資料。超出最大封包大小的 span 會被用戶端捨棄 (並發出指標以指示此情況)。另一種替代方法是使用非 UDP 傳輸，例如 Java 中的 HttpSender 外部連結 (目前並非適用於所有語言)。

指標

Jaeger 追蹤器會發出各種指標，關於它們已開始和完成的 span 或追蹤數量、有多少被取樣或未被取樣，以及從輸入要求中解碼追蹤內容或向後端回報 span 時是否有任何錯誤。

TODO 標準化並描述指標名稱和標籤 (問題 #572 外部連結、#611 外部連結)。

傳播格式

當 SpanContext 在網路上編碼為另一個服務的要求的一部分時，Jaeger 用戶端函式庫預設為以下指定的 Jaeger 原生傳播格式。此外，Jaeger 用戶端支援 Zipkin B3 格式 外部連結 和 W3C 追蹤內容 外部連結。

追蹤/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}
    • 以 16 進位格式表示的 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 建議行李鍵使用小寫烤肉串式命名法，例如 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 傳播格式時，行李值會進行 URL 編碼。

範例：當使用 HTTP_HEADERS 傳播格式時，以下程式碼序列

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

將產生以下 HTTP 標頭

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