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 の設定

CallIdConfig クラスによって提供される CallId プラグインの設定では、コール 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 を参照してください。