Envoy: トレーシング

tldr

勉強がてらにEnvoyのドキュメントを邦訳してみました。ベースはGoogle Translateで、ところどころ不自然な箇所を直しています。

原文としたのEnvoyのドキュメントはこちらのディレクトリ以下にあります（ライセンス：Apache License 2.0, NOTICE）。

トレーシング

概要

分散トレーシングを使用すると、開発者は大規模なサービス指向アーキテクチャでコールフローを視覚化することができます。シリアライゼーション、並列処理、および待ち時間の原因を理解する上で非常に貴重なことがあります。 Envoyは、システム全体のトレーシングに関連する3つの機能をサポートしています。

• リクエストIDの生成：Envoyは必要に応じてUUIDを生成し、x-request-id HTTPヘッダーを生成します。アプリケーションは、トレーシングだけでなく統合ロギングのためにx-request-idヘッダーを転送できます。
• クライアントトレーシングIDの参加：x-client-trace-idヘッダーを使用して、信頼されていない要求IDを信頼された内部のx-request-idに参加させることができます。
• 外部トレーシングサービスの統合：Envoyはプラグイン可能な外部トレーシング視覚化プロバイダをサポートしています。これらは2つのサブグループに分けられます。
• LightStep、Zipkin、またはZipkin互換のバックエンド（Jaegerなど）、およびDatadogなど、Envoyコードベースの一部である外部トレーサ。
• Instanaのように、サードパーティ製のプラグインとして提供される外部トレーサ。

他のトレーシングプロバイダのサポートを追加するのは難しくありません。

トレーシングを開始する方法

要求を処理するHTTP接続マネージャには、トレーシングオブジェクトを設定する必要があります。トレーシングを開始する方法はいくつかあります。

• x-client-trace-idヘッダーを介した外部クライアントによる。
• x-envoy-force-traceヘッダーを介した内部サービスによる。
• random_samplingランタイム設定によってランダムにサンプリングされます。

ルータフィルタはstart_child_spanオプションによって出力コールのための子スパンを作成することもできます。

トレーシングコンテキストの伝播

Envoyは、メッシュ内のサービス間の通信に関するトレーシング情報を報告する機能を提供します。ただし、コールフロー内のさまざまなプロキシによって生成されたトレーシング情報を相互に関連付けることができるようにするには、サービスはインバウンド要求とアウトバウンド要求の間に特定のトレーシングコンテキストを伝播する必要があります。

どのトレーシングプロバイダーが使用されている場合でも、サービスはx-request-idを伝播して、呼び出されたサービス間でのログ記録を有効にする必要があります。

トレーシングプロバイダーは、スパン間の親子関係（論理作業単位）を理解できるようにするために、追加のコンテキストも必要とします。これは、LightStep（OpenTracing API経由）またはZipkinトレーサをサービス自体の中で直接使用して、着信要求からトレーシングコンテキストを抽出し、それを後続の発信要求に挿入することで実現できます。このアプローチにより、サービスはサービス内で行われている作業を記述した追加のスパンを作成することもできます。これは、エンドツーエンドのトレーシングを調べるときに役立ちます。

あるいは、トレーシングコンテキストはサービスによって手動で伝播されることができます。

• LightStepトレーサを使用する場合、Envoyは他のサービスにHTTPリクエストを送信しながらx-ot-span-context HTTPヘッダを伝播するためにサービスに依存します。
• Zipkinトレーサを使用する場合、Envoyはサービスに依存してB3 HTTPヘッダ（x-b3-traceid、x-b3-spanid、x-b3-parentpanid、x-b3-sampling、およびx-b3-flags）を伝達します。 x-b3-samplingヘッダーは、特定の要求に対するトレーシングを有効または無効にするために外部クライアントからも提供されます。さらに、より圧縮されたフォーマットである単一のb3ヘッダー伝播フォーマットがサポートされています。
• Datadogトレーサーを使用する場合、EnvoyはDatadog固有のHTTPヘッダー（x-datadog-trace-id、x-datadog-parent-id、x-datadog-sampling-priority）を伝達するサービスに依存しています。

各トレーシングに含まれるデータ

エンドツーエンドのトレーシングは、1つ以上のスパンで構成されています。スパンは、開始時刻と期間を持ち、それに関連付けられたメタデータを含むことができる論理作業単位を表します。 Envoyによって生成された各スパンには、以下のデータが含まれています。

• --service-clusterによって設定された発信元サービスクラスター。
• リクエストの開始時間と期間
• --service-nodeを介して設定された発信ホスト。
• x-envoy-downstream-service-clusterヘッダーを介して設定されたダウンストリームクラスター。
• HTTP URL
• HTTPメソッド
• HTTPレスポンスコード
• システム固有のメタデータをトレーシングします。

スパンには、呼び出されたサービスのホストとしてデフォルトで定義されている名前（または操作）も含まれています。ただし、これはroute.Decoratorを使ってカスタマイズできます。名前はx-envoy-decorator-operationヘッダーを使用して上書きすることもできます。

Envoyは自動的にスパンをトレーシングコレクタに送ります。トレーシングコレクタによっては、グローバルに一意なリクエストID x-request-id（LightStep）やトレーシングID設定（ZipkinとDatadog）などの共通情報を使用して複数のスパンがステッチされます。見る

v2 APIリファレンス

Envoyでトレーシングを設定する方法の詳細については。