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 アーティファクトを追加します。
implementation(ktorLibs.client.callId)implementation ktorLibs.client.callId<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-client-call-id-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>CallId のインストール
CallId プラグインをアプリケーションにインストールするには、指定されたモジュールモジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。内の install 関数に渡します。 以下の例は、CallId をインストールする方法を示しています。
embeddedServer()関数呼び出し内。Applicationクラスで明示的に定義されたmodule()拡張関数内。
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)
}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に設定します。
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 を参照してください。
