クライアントライブラリ

バージョン 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 シム/ブリッジを使用して、Jaeger クライアントを置き換えることをお勧めします。

タイムライン

2021年末までは、プルリクエストの受け入れと Jaeger クライアントの新しいリリースを継続する予定です。2022年1月には**6ヶ月間の**コードフリーズ期間に入ります。この期間中は、セキュリティ関連の修正を除き、新機能を含むプルリクエストは受け付けません。その後、クライアントライブラリのリポジトリをアーカイブし、新しい変更を受け付けなくなります。

OpenTelemetry への移行

OpenTelemetry プロジェクトは、OpenTracing ブリッジ/シムを介して OpenTracing API から OpenTelemetry SDK への移行ガイドを公開しました。OpenTelemetry SDK には、成熟度と機能のレベルが異なる場合があります。詳細情報が利用可能になり次第、以下の情報を更新していきます。

バゲージサポート

OpenTelemetry は、OpenTracing とは異なる方法でバゲージの伝播を実装しており、完全に同等ではありません。OpenTelemetry では、`context` レイヤーがトレーシング API よりも下にあり、不変のコンテキストオブジェクトに依存していますが、OpenTracing のバゲージは変更可能な `span` に格納されます（子スパンを開始する際に、トリッキーな競合状態が発生することがあります）。

皆様の力が必要です！

不正確な点を見つけたり、追加できる情報があれば、ドキュメントリポジトリで問題点やプルリクエストを作成してください。機能が不足していて必要な場合は、それぞれの OpenTelemetry リポジトリでチケットを作成するか、貢献してください。たとえば、Jaeger のリモートサンプラーは、まだすべての OpenTelemetry SDK で実装されていませんが、Jaeger のコードベースからの移植は比較的簡単な作業です。

Jaeger コードのコピー

Jaeger モジュールに直接依存するのではなく、関連する Jaeger クライアントの部分をコピーすることを OpenTelemetry SDK の作成者にお勧めします。そのため、寛大な APL2 ライセンスを使用しています。コードをコピーする際には、ライセンス要件を尊重する正しい方法として、著作権表示を保持してください。たとえば、Jaeger の作成者は、もともと Uber で記述されたコードについても同様の処理を行いました。

// 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
- 移行ガイド: シムのREADMEに記載されています。

Node.js

OpenTelemetry SDK: https://github.com/open-telemetry/opentelemetry-js
- リモートサンプリング: ？
- 内部SDKメトリクス: 該当なし
OpenTracingブリッジ: opentelemetry-shim-opentracing
- 移行ガイド: シムの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
- 移行ガイド: シムのREADMEに記載されていますが、非常に簡潔です。

C++

OpenTelemetry SDK: https://github.com/open-telemetry/opentelemetry-cpp
- リモートサンプリング: ？
- 内部SDKメトリクス: 該当なし
OpenTracingブリッジ: 該当なし
- 移行ガイド: 該当なし

はじめに

すべてのJaegerクライアントライブラリは、OpenTracing API をサポートしています。以下のリソースは、OpenTracingを使用してアプリケーションをインストルメントする方法に関する詳細情報を提供しています。

OpenTracingチュートリアル (Java、Go、Python、Node.js、C#)
詳細なブログ記事 GoでOpenTracingを用いたHTTPリクエストレイテンシのトレース
公式OpenTracingドキュメントおよびその他の資料はopentracing.io にあります。
GitHubのopentracing-contrib組織には、JAXRS & Dropwizard (Java)、Flask & Django (Python)、Go標準ライブラリなど、多くの一般的なフレームワークのための既製のインストルメンテーションを備えた多くのリポジトリが含まれています。

このページの残りの部分には、OpenTracing APIで既にインストルメント化されているアプリケーションでJaegerトレーサーを構成およびインスタンス化する方法に関する情報が含まれています。

用語

このドキュメントでは、クライアントライブラリ、インストルメンテーションライブラリ、およびトレーサーという用語を互換的に使用しています。

サポートされているライブラリ

以下のクライアントライブラリは正式にサポートされています。

言語	GitHubリポジトリ
Go	jaegertracing/jaeger-client-go
Java	jaegertracing/jaeger-client-java
Node.js	jaegertracing/jaeger-client-node
Python	jaegertracing/jaeger-client-python
C++	jaegertracing/jaeger-client-cpp
C#	jaegertracing/jaeger-client-csharp

他の言語のライブラリは現在開発中です。 issue #366 を参照してください。

Jaegerトレーサーの初期化

初期化構文は言語によってわずかに異なります。それぞれのレポジトリのREADMEを参照してください。一般的なパターンは、Tracerを明示的に作成するのではなく、Configurationクラスを使用してTracerを作成することです。Configurationを使用すると、デフォルトのサンプラーの変更やJaegerエージェントの場所の変更など、Tracerのパラメーター化が簡素化されます。

Tracer内部

サンプリング

アーキテクチャ | サンプリングを参照してください。

レポーター

Jaegerトレーサーは、完了したスパンを処理するためにレポーターを使用します。通常、Jaegerライブラリには次のレポーターが付属しています。

NullReporterは、スパンに対して何も実行しません。単体テストで役立ちます。
LoggingReporterは、スパンが完了したという事実をログに記録するだけです。通常、トレースID、スパンID、および操作名を印刷することによって行われます。
CompositeReporterは、他のレポーターのリストを受け取り、それらを1つずつ呼び出します。
RemoteReporter（デフォルト）は、完了したスパンをメモリに一定数バッファリングし、senderを使用して、スパンのバッチをプロセス外でJaegerバックエンドに送信します。senderは、スパンをワイヤフォーマット（例：ThriftまたはJSON）にシリアル化し、バックエンドコンポーネント（例：UDPまたはHTTP経由）と通信する役割を担います。

EMSGSIZEとUDPバッファの制限

デフォルトでは、JaegerライブラリはUDP senderを使用して、完了したスパンをjaeger-agentデーモンに報告します。デフォルトの最大パケットサイズは65,000バイトで、ループバックインターフェースを介してエージェントに接続するときにセグメンテーションなしで送信できます。ただし、一部のOS（特にMacOS）では、このGitHubの問題で述べられているように、UDPパケットの最大バッファサイズが制限されています。EMSGSIZEエラーの問題が発生した場合は、カーネルで制限を引き上げることを検討してください（例については、問題を参照してください）。また、クライアントライブラリでより小さい最大パケットサイズを使用するように構成することもできますが、大きなスパンがある場合（たとえば、大量のデータをログに記録する場合）は問題が発生する可能性があります。最大パケットサイズを超えるスパンはクライアントによって破棄されます（それを示すメトリックが発行されます）。別の方法として、JavaのHttpSender （現在、すべての言語で利用可能ではありません）などのUDP以外のトランスポートを使用することもできます。

メトリクス

Jaegerトレーサーは、開始および終了したスパンまたはトレースの数、サンプリングまたはサンプリングされなかったスパンの数、インバウンドリクエストからのトレースコンテキストのデコードまたはバックエンドへのスパンの報告におけるエラーの有無など、さまざまなメトリクスを生成します。

メトリック名とラベルの標準化と説明を行う必要があります（#572 、#611 ）。

伝搬フォーマット

SpanContextがリクエストの一部としてワイヤ上にエンコードされるとき、Jaegerクライアントライブラリは、下記で指定されているJaegerネイティブ伝搬フォーマットをデフォルトで使用します。さらに、JaegerクライアントはZipkin B3フォーマットとW3C Trace-Context をサポートしています。

トレース/スパンID

キー

uber-trace-id

HTTPでは大文字と小文字を区別しません。
ヘッダーの大文字と小文字を保持するプロトコルでは小文字です。

値

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

{trace-id}
- 16進形式の64ビットまたは128ビットの乱数
- 可変長にすることができます。短い値は左側に0埋めされます。
  - 受信者は、32文字より短い16進文字列を受け入れ、左側に0埋めする必要があります。
  - 送信者は、長さが正確に16文字または32文字の16進文字列を生成する必要があります。
- 一部の言語のクライアントは128ビットをサポートしており、移行が保留中です。
- 0の値は無効です。
{span-id}
- 16進形式の64ビット乱数
- 可変長にすることができます。短い値は左側に0埋めされます。
  - 受信者は、16文字より短い16進文字列を受け入れ、左側に0埋めする必要があります。
  - 送信者は、正確に16文字の16進文字列を生成する必要があります。
- 0の値は無効です。
{parent-span-id}
- 親スパンIDを表す16進形式の64ビット値
- 非推奨。ほとんどのJaegerクライアントは受信側では無視しますが、送信側には引き続き含まれています。
- 0の値は有効であり、「ルートスパン」を意味します（無視されない場合）。
{flags}
- 1バイトのビットマップ。1つまたは2つの16進数字として（先頭のゼロは省略できます）。
- ビット1（最右端、最下位、ビットマスク0x01）は「サンプリング済み」フラグです。
  - 1は、トレースがサンプリングされており、すべてのダウンストリームサービスがそれを尊重するようにアドバイスされていることを意味します。
  - 0は、トレースがサンプリングされておらず、すべてのダウンストリームサービスがそれを尊重するようにアドバイスされていることを意味します。
    - ダウンストリームサービスが、トレースレベルが低すぎる場合にアップサンプリングできるようにする新しい機能を検討しています。
- ビット2（ビットマスク0x02）は「デバッグ」フラグです。
  - デバッグフラグは、サンプリング済みフラグが設定されている場合にのみ設定する必要があります。
  - バックエンドに、このトレースを絶対にドロップしないように指示します。
- ビット3（ビットマスク0x04）は使用されていません。
- ビット4（ビットマスク0x08）は「firehose」フラグです。
  - 「firehose」とタグ付けされたスパンは、ストレージへのインデックス付けから除外されます。
  - トレースは、トレースIDでのみ取得できます（通常、ログなどの他のソースから入手できます）。
- その他のビットは使用されていません。

Baggage

キー: uberctx-{baggage-key}
値: 文字列としての{baggage-value}（下記の値のエンコーディングを参照）
制限事項: HTTPヘッダーは大文字と小文字を区別しないため、Jaegerではbaggageキーを小文字でケバブケース（例: my-baggage-key-1）にすることを推奨します。

例: 次のコードシーケンス

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

は、次のHTTPヘッダーになります。

uberctx-key1: value1
uberctx-key2: value2

値のエンコーディング

OpenTracingでは、プレーンテキストヘッダーにHTTP_HEADERSとTEXT_MAPの2つの形式を定義しています。前者は、HTTPプロトコルのヘッダーコンテキストによる制限に対処するために導入されましたが、後者は制限を課しません（例：Kafkaレコードヘッダーで使用できます）。Jaeger SDKにおけるこれらの2つの形式の主な違いは、HTTP_HEADERS伝播形式を使用する場合、baggage値がURLエンコードされることです。

例: HTTP_HEADERS伝播形式を使用する場合、次のコードシーケンス

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

は、次のHTTPヘッダーになります。

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