Skip to content
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 アーティファクトを追加します。

kotlin
implementation(ktorLibs.client.callId)
上記コードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
groovy
implementation ktorLibs.client.callId
上記コードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-call-id-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

CallId のインストール ​

CallId プラグインをアプリケーションにインストールするには、指定されたモジュールモジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。内の install 関数に渡します。 以下の例は、CallId をインストールする方法を示しています。

  • embeddedServer() 関数呼び出し内。
  • Application クラスで明示的に定義された module() 拡張関数内。
kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.client.plugins.callid.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(CallId)
        // ...
    }.start(wait = true)
}
kotlin
import io.ktor.server.application.*
import io.ktor.client.plugins.callid.*
// ...
fun Application.module() {
    install(CallId)
    // ...
}

CallId の設定 ​

CallIdConfig クラスによって提供される CallId プラグインの設定を使用すると、コール ID を生成して呼び出しコンテキストに追加できます。

コール ID の生成 ​

特定のリクエストに対して、次のいずれかの方法でコール ID を生成します。

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

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

  • generate() 関数を使用すると、送信リクエスト用のコール ID を生成できます。コール ID の生成に失敗した場合は、null を返します。
kotlin
install(CallId) {
    generate { "call-id-client-2" }
}

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

コール ID の追加 ​

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

  • intercept() 関数を使用すると、CallIdInterceptor を使用してリクエストにコール ID を追加できます。
kotlin
install(ClientCallId) {
    intercept { request, callId ->
        request.header(HttpHeaders.XRequestId, callId)
    }
}
  • addToHeader() 関数は、指定されたヘッダーにコール ID を追加します。ヘッダーをパラメータとして受け取り、デフォルトは HttpHeaders.XRequestId です。
kotlin
install(CallId) {
    addToHeader(HttpHeaders.XRequestId)
}

例 ​

以下の例では、Ktor クライアント用の CallId プラグインを設定して、新しいコール ID を生成し、それをヘッダーに追加します。

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

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

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

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

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

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