Client Plugin

Ktor Clientでのリクエストのトレース

必須の依存関係: io.ktor:ktor-client-call-id

コード例: client-call-id

CallIdプラグインを使用すると、一意のコールIDを使用してクライアントリクエストをエンドツーエンドでトレースできます。これは、マイクロサービスアーキテクチャにおいて、リクエストがいくつのサービスを経由しても、コールを追跡するために特に役立ちます。

呼び出しスコープには、コルーチンコンテキストにすでにコールIDが含まれている場合があります。デフォルトでは、プラグインは現在のコンテキストを使用してコールIDを取得し、それをHttpHeaders.XRequestIdヘッダーを使用して特定のコールのコンテキストに追加します。

さらに、スコープにコールIDがない場合、プラグインを構成して新しいコールIDを生成し、適用することができます。

サーバー側では、KtorはクライアントリクエストのトレースにCallIdプラグインを提供します。

依存関係の追加

CallIdを使用するには、ビルドスクリプトにktor-client-call-idアーティファクトを含める必要があります:

Gradle (Kotlin)Gradle (Groovy)Maven

CallIdのインストール

アプリケーションにCallIdプラグインをインストールするには、指定された

モジュール

モジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。

のinstall関数に渡します。 以下のコードスニペットは、CallIdをインストールする方法を示しています...

• ... embeddedServer関数呼び出し内で。
• ... Applicationクラスの拡張関数である、明示的に定義されたmodule内で。

embeddedServermodule

CallIdの構成

CallIdプラグインの構成は、CallIdConfigクラスによって提供され、コールIDを生成してコールコンテキストに追加できます。

コールIDの生成

特定の目的のコールIDを以下のいずれかの方法で生成します:

• useCoroutineContextプロパティは、デフォルトで有効になっており、現在のCoroutineContextを使用してコールIDを取得するジェネレーターを追加します。この機能を無効にするには、useCoroutineContextをfalseに設定します:

install(CallId) {
    useCoroutineContext = false
}

Ktorサーバーでは、CallIdプラグインを使用してCoroutineContextにコールIDを追加します。

• generate()関数は、送信リクエストのコールIDを生成できます。コールIDの生成に失敗した場合、nullを返します。

install(CallId) {
    generate { "call-id-client-2" }
}

コールIDを生成するために複数のメソッドを使用できます。この方法では、最初の非null値が適用されます。

コールIDの追加

コールIDを取得した後、リクエストに追加するための以下のオプションが利用可能です:

• intercept()関数は、CallIdInterceptorを使用してリクエストにコールIDを追加できます。

install(ClientCallId) {
    intercept { request, callId ->
        request.header(HttpHeaders.XRequestId, callId)
    }
}

• addToHeader()関数は、コールIDを指定されたヘッダーに追加します。ヘッダーをパラメータとして受け取り、デフォルトはHttpHeaders.XRequestIdです。

install(CallId) {
    addToHeader(HttpHeaders.XRequestId)
}

例

以下の例では、KtorクライアントのCallIdプラグインが、新しいコールIDを生成してヘッダーに追加するように構成されています:

val client = HttpClient(CIO) {
    install(CallId) {
        generate { "call-id-client" }
        addToHeader(HttpHeaders.XRequestId)
    }
}

プラグインはコルーチンコンテキストを使用してコールIDを取得し、generate()関数を利用して新しいコールIDを生成します。最初の非nullのコールIDは、addToHeader()関数を使用してリクエストヘッダーに適用されます。

Ktorサーバーでは、CallIdサーバープラグインのretrieve関数を使用して、ヘッダーからコールIDを取得できます。

install(CallId) {
    retrieveFromHeader(HttpHeaders.XRequestId)
}

このようにして、Ktorサーバーはリクエストの指定されたヘッダーからIDを取得し、それをコールのcallIdプロパティに適用します。

完全な例については、client-call-idを参照してください。