- 相関IDを使用したディストリビューションリクエストの調査
- ディストリビューショントレースの有効化
- GitLab開発キットでJaegerを使う
- GitLab Developer KitなしでJaegerを使う場合
分散トレース - 開発者向けガイドライン
GitLabはディストリビューション・トレース用にインストゥルメント化されています。
オープントレースによると
分散トレース(分散リクエストトレースとも呼ばれる)は、アプリケーション、特にマイクロサービスアーキテクチャを使用して構築されたアプリケーションのプロファイリングとモニタリングに使用される手法です。 分散トレースは、障害が発生する場所やパフォーマンス低下の原因を突き止めるのに役立ちます。
分散トレースは、GitLabアプリケーションのさまざまなコンポーネントを通過するリクエストのライフサイクルを理解するのに特に役立ちます。 現時点では、Workhorse、Rails、Sidekiq、Gitalyがトレース・インストゥルメンテーションをサポートしています。
ディストリビューション・トレーシングは、無効化された場合には最小限のオーバーヘッドしか追加しませんが、有効化された場合にはわずかなオーバーヘッドしか課しません。 このため、本番環境での問題、特にパフォーマンスの問題を診断するのに役立ちます。
相関IDを使用したディストリビューションリクエストの調査
GitLabアプリケーションは、リクエスト内の様々なコンポーネント間で相関IDを渡します。 相関IDは、異なるGitLabサブシステム(例えば、Rails、Workhorse)間で単一のリクエストを相関させるために使用される、単一のリクエストに固有のトークンです。 相関IDはログ出力に含まれるため、エンジニアは相関IDを使用して異なるサブシステムからのログを相関させ、システムを通してリクエストのエンドツーエンドのパスをより良く理解することができます。 リクエストがプロセス境界を通過するとき、相関IDは送信リクエストに注入されます。 これにより、相関IDの各ダウンストリームサブシステムへの伝播が可能になります。
相関IDは通常、特定のWebリクエストに応答してRailsアプリケーション内で生成されます。 ユーザが直面するシステムの中には、ユーザのリクエストに応答して相関IDを生成しないものもあります(たとえば、SSH経由のGitプッシュなど)。
相関IDを使用するための開発者ガイドライン
新しいシステムにトレースをインテグレーションする場合、開発者は相関IDについて特定の仮定をすることを避けるべきです。 以下のガイドラインはGitLabのすべてのサブシステムに適用されます:
- 相関IDは常にオプションです。
- トレース以外の機能が、上流システムからの相関IDの存在に依存することはありません。
- 相関IDは常にフリーテキストです。
- 相関IDは、コンテキスト(ユーザー名やIPアドレスなど)の受け渡しに使用してはなりません。
- 相関IDは決して_解析_したり、他の方法(例えば分割など)で操作してはいけません。
LabKitライブラリは、Goプログラミング言語でGitLabの相関IDを扱うための標準化されたインターフェイスを提供します。 LabKitは、Go以外のGitLabサブシステムでトレースと相関IDを扱う開発者のためのリファレンス実装として使用できます。
ディストリビューショントレースの有効化
GitLabはGITLAB_TRACING
環境変数を使って分散トレースを設定します。 すべてのコンポーネント(Workhorse、Railsなど)で同じ設定が使われます。
GITLAB_TRACING
が設定されていない場合、アプリケーションはインスツルメンテーショ ンを受けません。つまり、オーバーヘッドはまったくありません。
GITLAB_TRACING
を有効にするには、URLのような形式で有効な_「configuration-string」_値を設定する必要があります:
GITLAB_TRACING=opentracing://<driver>?<param_name>=<param_value>&<param_name_2>=<param_value_2>
この例では、次のような仮想値があります:
-
driver
GitLab は をサポートしています。 将来的には、他のトレース実装もサポートされるかもしれません。jaeger
-
param_name
param_value
: これらはドライバ固有の設定値です。Jaegerの設定パラメータは、このドキュメントでさらに詳しく説明されています。 これらはURLエンコードされている必要があります。複数の値は、URLのように 文字で区切られている必要があります。&
GitLab開発キットでJaegerを使う
GitLabが最初にサポートするトレース実装はJaegerで、GitLab Development KitはJaegerによるディストリビューショントレースをすぐにサポートします。
GDK環境からトレースにアクセスする最も簡単な方法は、パフォーマンスバーからアクセスすることです。 これは、ブラウザウィンドウでp
b
と入力すると表示されます。
パフォーマンス・バーを有効にしたら、パフォーマンス・バーのトレース・リンクをクリックしてJaeger UIに移動します。
Jaegerの検索UIは、現在のリクエストのCorrelation-ID
。通常、この検索は単一のトレース結果を返します。この結果をクリックすると、階層的な時間軸でトレースの詳細が表示されます。
GitLab Developer KitなしでJaegerを使う場合
分散トレースは、本番環境やステージング環境だけでなく、GDK以外の開発環境でも、トラブルシューティングのために有効にすることができます。 現時点では、この機能は実験的なものであり、本番環境ではサポートされていないことに注意してください。 この最初のリリースでは、開発環境でのデバッグにのみ使用することを意図しています。
イェーガー・トレーシングは3つのステップを経て有効になります:
- イェーガーをスタートさせてください。
GITLAB_TRACING
環境変数 を設定します。- GitLabアプリケーションを起動します。
- ブラウザでJaeger Search UIにアクセスしてください。
1. イェーガー始動
Jaegerには多くの設定オプションがありますが、トレース保存にメモリを使用する “all-in-one “モードで起動するのが非常に簡単です(したがって、非パーシステント)。 “all-in-one “モードの主な利点は、使いやすさです。
より詳細な設定オプションについては、イェーガーのドキュメントを参照してください。
Dockerの使用
もしDockerが使えるのであれば、以下のコマンドを使ってDockerからJaeger all-in-oneを実行するのが簡単です:
$ docker run \
--rm \
-e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \
-p 5775:5775/udp \
-p 6831:6831/udp \
-p 6832:6832/udp \
-p 5778:5778 \
-p 16686:16686 \
-p 14268:14268 \
-p 9411:9411 \
jaegertracing/all-in-one:latest
イェーガー・プロセスの使用
Dockerがなくても、オールインワンのプロセスはセットアップが簡単です。
- お使いのプラットフォームの最新のJaegerリリースをダウンロードしてください。
- アーカイブを解凍し、
bin/all-in-one
プロセスを実行します。
これで、デフォルトのリスニング・ポートでプロセスが開始されるはずです。
2. GITLAB_TRACING
環境変数の設定
Jaegerを起動したら、GITLAB_TRACING
変数に適切な設定文字列を設定する必要があります。
TL;DR:すべてを同じホスト上で実行する場合は、以下の値を使用してください:
export GITLAB_TRACING="opentracing://jaeger?http_endpoint=http%3A%2F%2Flocalhost%3A14268%2Fapi%2Ftraces&sampler=const&sampler_param=1"
この設定文字列は、Jaegerドライバopentracing://jaeger
、以下のオプションを使用します:
名称 | 値 | 説明 |
---|---|---|
http_endpoint
| http://localhost:14268/api/traces
| Jaeger がトレース情報をhttp://localhost:14268/ 上の HTTP エンドポイントに送信するように設定します。 あるいは、upd_endpoint を使うこともできます。
|
sampler
| const
| Jaeger がコンスタント・サンプラーを使うように設定します(オンかオフのどちらか)。 |
sampler_param
| 1
|
すべての_トレースをサンプリングするようにconst サンプラーを設定します。0 を使用すると、トレースはサンプリングさ_れません。
|
その他のパラメータ値も可能です:
名称 | 例 | 説明 |
---|---|---|
udp_endpoint
| localhost:6831
| これはデフォルトです。 Jaegerがコンパクトなthriftプロトコルを使って、ポート6831 のUDPリスナーにトレース情報を送信するように設定します。 このプロトコルを使うと、Jaeger Client forRubyでいくつかイシューが発生するので注意してください。
|
sampler
| probabalistic
| Jaeger が確率的ランダムサンプラーを使うように設定します。 サンプルのレートはsampler_param の値で設定します。
|
sampler_param
| 0.01
|
0.01 の比率を使用して、probabalistic サンプラーがトレースの_1%_をランダムにサンプリングするように設定します。
|
GITLAB_TRACING
値を設定する必要があります。3. GitLabアプリケーションを起動します。
GITLAB_TRACING
環境変数がすべての GitLab サービスに exporter されたら、アプリケーションを起動します。
GITLAB_TRACING
が適切に設定されている場合、アプリケーションは起動時にこのログを記録します:
13:41:53 gitlab-workhorse.1 | 2019/02/12 13:41:53 Tracing enabled
...
13:41:54 gitaly.1 | 2019/02/12 13:41:54 Tracing enabled
...
GITLAB_TRACING
が正しく設定されていない場合もログに記録されます:
13:43:45 gitaly.1 | 2019/02/12 13:43:45 skipping tracing configuration step: tracer: unable to load driver mytracer
デフォルトでは、GitLabはJaegerトレーサーを同梱していますが、コンパイル時に他のトレーサーを含めることができます。 この方法の詳細は、LabKitトレーシングドキュメントに記載されています。
トレースに関するログメッセージが出力されない場合、GITLAB_TRACING
環境変数が設定されていない可能性があります。
4. イェーガー検索UIを開く
デフォルトでは、イェーガーの検索UIはhttp://localhost:16686/searchで利用可能です。