Jaeger コンポーネントは、トレースデータの保存または取得のための様々な API を実装しています。

API の互換性保証を説明するために、以下のラベルを使用します。

• stable - API は下位互換性を保証します。将来、破壊的な変更を行う必要がある場合は、新しい API バージョン（例：/api/v2 URL プレフィックスまたは IDL の異なる名前空間）が作成されます。
• internal - これらの API は、Jaeger コンポーネント間の内部通信を目的としており、外部コンポーネントによる使用はお勧めしません。
• deprecated - 従来の理由でのみ維持されている API で、将来廃止される予定です。

Jaeger v1.32 以降、gRPC エンドポイントを提供する **jaeger-collector** と **jaeger-query** のサービスポートは、gRPC リフレクション  を有効にします。しかしながら、内部で使用されている gogo/protobuf には 公式の golang/protobuf との互換性の問題  があり、その結果、現在 `list` リフレクションコマンドのみが正しく動作しています。

Span レポート API

**jaeger-agent** と **jaeger-collector** は、Span を受信できる Jaeger バックエンドの 2 つのコンポーネントです。現時点では、2 つの非重複 API セットをサポートしています。

OpenTelemetry Protocol (stable)

v1.35 以降、Jaeger バックエンドは、ネイティブの OpenTelemetry Protocol (OTLP)  で OpenTelemetry SDK からトレースデータを受信できます。OpenTelemetry SDK を Jaeger エクスポーターで設定したり、OpenTelemetry Collector を OpenTelemetry SDK と Jaeger バックエンドの間にデプロイしたりする必要はなくなりました。

OTLP データは、(1) バイナリ gRPC、(2) HTTP 上のプロトコルバッファ、(3) HTTP 上の JSON の形式で受け付けられます。OTLP レシーバーの詳細については、公式ドキュメント  を参照してください。**jaeger-collector** では、すべての構成オプションがサポートされているわけではありません（--collector.otlp.* CLI フラグ を参照）。Jaeger は他のテレメトリタイプを保存しないため、トレースデータのみが受け付けられます。

UDP 上の Thrift (stable)

jaeger-agent は、Thrift形式のUDP経由でのみspanを受信できます。主要なAPIは、jaeger.thrift  IDLファイル（jaeger-idl リポジトリに位置する）で定義されたThriftエンコードされたBatch構造体を含むUDPパケットです。ほとんどのJaegerクライアントはThriftのcompactエンコーディングを使用しますが、一部のクライアントライブラリ（特にNode.js）はこれをサポートしておらず、Thriftのbinaryエンコーディング（異なるUDPポートに送信）を使用します。jaeger-agentのAPIは、agent.thrift  IDLファイルによって定義されています。

レガシーな理由から、jaeger-agentはZipkin形式のUDP経由でのspanも受け付けますが、非常に古いバージョンのJaegerクライアントのみがその形式でデータを送信でき、正式には非推奨となっています。

gRPC経由のProtobuf（安定版）

一般的なJaegerのデプロイメントでは、jaeger-agentはクライアントからspanを受信し、jaeger-collectorに転送します。Jaeger v1.11以降、jaeger-agentとjaeger-collector間の公式で推奨されるプロトコルは、collector.proto  IDLファイルで定義されたjaeger.api_v2.CollectorService gRPCエンドポイントです。同じエンドポイントを使用して、SDKからjaeger-collectorに直接トレースデータを送信することもできます。

HTTP経由のThrift（安定版）

アプリケーションコードがサーバーレス関数として実行されている場合など、アプリケーションの横にjaeger-agentをデプロイできない場合があります。このようなシナリオでは、SDKを構成して、HTTP/HTTPS経由でjaeger-collectorに直接spanを送信できます。

同じjaeger.thrift ペイロードを、例えばhttps://jaeger-collector:14268/api/tracesのような/api/tracesエンドポイントにHTTP POSTリクエストで送信できます。Batch構造体はThriftのbinaryエンコーディングを使用してエンコードする必要があり、HTTPリクエストはコンテンツタイプヘッダーを指定する必要があります。

Content-Type: application/vnd.apache.thrift.binary

HTTP経由のJSON（該当なし）

jaeger-collectorが受け付ける公式のJaeger JSON形式はありません。JaegerはOpenTelemetryプロトコルをJSON経由で受け付けます（上記参照）。

Zipkin形式（安定版）

jaeger-collectorは、JSON v1/v2およびThriftという複数のZipkinデータ形式のspanも受け付けることができます。jaeger-collectorは、Zipkinコレクターで使用されるポート9411など、Zipkin HTTPサーバーを有効にするように構成する必要があります。このサーバーは、POSTリクエストを期待する2つのエンドポイントを有効にします。

• Zipkin JSON v1またはZipkin Thrift形式のspanを送信するための/api/v1/spans。
• Zipkin JSON v2のspanを送信するための/api/v2/spans。

トレース取得API

ストレージに保存されたトレースは、jaeger-queryサービスを呼び出すことで取得できます。

gRPC/Protobuf（安定版）

プログラムでトレースおよびその他のデータを取得するための推奨方法は、query.proto  IDLファイルで定義されたjaeger.api_v2.QueryService gRPCエンドポイントを使用することです。デフォルトの構成では、このエンドポイントはjaeger-query:16685からアクセスできます。

HTTP JSON（内部）

Jaeger UIは、JSON API経由でjaeger-queryサービスと通信します。例えば、トレースはhttps://jaeger-query:16686/api/traces/{trace-id-hex-string}へのGETリクエストで取得できます。このJSON APIは意図的にドキュメント化されておらず、変更される可能性があります。

リモートストレージAPI（安定版）

grpcストレージタイプ（別名リモートストレージ）を使用する場合、Jaegerコンポーネントは、これらのバックエンドがgRPC リモートストレージAPI を実装している限り、カスタムストレージバックエンドを使用できます。

リモートサンプリング設定（安定版）

このAPIは、sampling.proto IDLファイルで定義されたJaegerのリモートサンプリングプロトコルをサポートしています。

jaeger-agentとjaeger-collectorの両方がこのAPIを実装しています。コレクターをサンプリング戦略で構成する方法の詳細については、リモートサンプリングを参照してください。jaeger-agentは単にjaeger-collectorのプロキシとして機能しています。

次の表は、サンプリング戦略のクエリに使用できるさまざまなエンドポイントと形式をリストしています。公式のHTTP/JSONエンドポイントは、標準のProtobufからJSONへのマッピング を使用します。

例

オールインワンを1つのターミナルで実行

$ go run ./cmd/all-in-one \
  --sampling.strategies-file=cmd/all-in-one/sampling_strategies.json

別のターミナルで異なるエンドポイントをクエリ

# Collector
$ curl "http://localhost:14268/api/sampling?service=foo"
{"strategyType":"PROBABILISTIC","probabilisticSampling":{"samplingRate":1}}

# Agent
$ curl "http://localhost:5778/sampling?service=foo"
{"strategyType":"PROBABILISTIC","probabilisticSampling":{"samplingRate":1}}

# Agent, legacy endpoint / (not recommended)
$ curl "http://localhost:5778/?service=foo"
{"strategyType":0,"probabilisticSampling":{"samplingRate":1}}

サービス依存関係グラフ（内部）

/api/dependenciesエンドポイントでjaeger-queryサービスから取得できます。GETリクエストは2つのパラメーターを期待します。

• endTs（エポックからのミリ秒数）- 時間区間の終了
• lookback（ミリ秒）- 時間区間の長さ（つまり、開始時間 + lookback = 終了時間）。

返されるJSONは、(呼び出し元、呼び出し先、カウント)というタプルで表されるエッジのリストです。

サービスグラフへのプログラムによるアクセスには、上記で説明したgRPC/Protobuf APIが推奨されます。

サービスパフォーマンスモニタリング（内部）

SPMドキュメントを参照してください。