Ktor Serverでのリクエストの追跡
必要な依存関係: io.ktor:ktor-server-call-id
コード例: call-id
ネイティブサーバーKtorはKotlin/Nativeをサポートしており、追加のランタイムや仮想マシンなしでサーバーを実行できます。のサポート: ✅
CallId プラグインを使用すると、一意のリクエストIDまたはコールIDを使用して、クライアントリクエストをエンドツーエンドで追跡できます。通常、KtorでコールIDを扱う手順は次のようになります。
- まず、次のいずれかの方法で特定のリクエストに対するコールIDを取得する必要があります。
- 次に、Ktorは事前定義された辞書を使用して、取得または生成されたコールIDを検証します。独自の検証条件を指定することも可能です。
- 最後に、
X-Request-Idなどの特定のヘッダーを使用して、コールIDをクライアントに送信できます。
CallId を CallLogging と併用すると、コールIDをMDCコンテキストに配置し、各リクエストのコールIDを表示するようにロガーを設定できるため、呼び出しのトラブルシューティングに役立ちます。
クライアント側では、Ktorはクライアントリクエストを追跡するための CallId プラグインを提供しています。
依存関係の追加
CallId を使用するには、ビルドスクリプトに ktor-server-call-id アーティファクトを追加します。
implementation(ktorLibs.server.callId)implementation ktorLibs.server.callId<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-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.server.plugins.callid.*
fun main() {
embeddedServer(Netty, port = 8080) {
install(CallId)
// ...
}.start(wait = true)
}import io.ktor.server.application.*
import io.ktor.server.plugins.callid.*
// ...
fun Application.module() {
install(CallId)
// ...
}CallId の設定
コールIDの取得
CallId は、コールIDを取得するためのいくつかの方法を提供しています。
指定したヘッダーからコールIDを取得するには、
retrieveFromHeader関数を使用します。例:kotlininstall(CallId) { retrieveFromHeader(HttpHeaders.XRequestId) }また、
header関数を使用して、同じヘッダーでコールIDを取得および送信することもできます。必要に応じて、
ApplicationCallからコールIDを取得できます。kotlininstall(CallId) { retrieve { call -> call.request.header(HttpHeaders.XRequestId) } }
取得されたすべてのコールIDは、デフォルトの辞書を使用して検証される点に注意してください。
コールIDの生成
受信リクエストにコールIDが含まれていない場合は、generate 関数を使用して生成できます。
- 以下の例は、事前定義された辞書から指定された長さのコールIDを生成する方法を示しています。kotlin
install(CallId) { generate(10, "abcde12345") } - 以下の例では、
generate関数がコールIDを生成するためのブロックを受け取ります。kotlininstall(CallId) { val counter = atomic(0) generate { "generated-call-id-${counter.getAndIncrement()}" } }
コールIDの検証
取得または生成されたすべてのコールIDは、以下のようなデフォルトの辞書を使用して検証されます。
CALL_ID_DEFAULT_DICTIONARY: String = "abcdefghijklmnopqrstuvwxyz0123456789+/=-"これは、大文字を含むコールIDは検証に失敗することを意味します。必要に応じて、verify 関数を使用してより柔軟なルールを適用できます。
install(CallId) {
verify { callId: String ->
callId.isNotEmpty()
}
}完全な例はこちらで確認できます: call-id
クライアントへのコールIDの送信
コールIDを取得または生成した後、クライアントに送信できます。
header関数を使用すると、コールIDを取得し、同じヘッダーで送信できます。kotlininstall(CallId) { header(HttpHeaders.XRequestId) }完全な例はこちらで確認できます: call-id
replyToHeader関数は、指定したヘッダーでコールIDを送信します。kotlininstall(CallId) { replyToHeader(HttpHeaders.XRequestId) }必要に応じて、
ApplicationCallを使用してレスポンス内でコールIDを送信できます。kotlinreply { call, callId -> call.response.header(HttpHeaders.XRequestId, callId) }
コールIDをMDCに設定する
CallId を CallLogging と併用すると、コールIDをMDCコンテキストに設定し、各リクエストのコールIDを表示するようにロガーを設定できるため、呼び出しのトラブルシューティングに役立ちます。これを行うには、CallLogging 設定ブロック内で callIdMdc 関数を呼び出し、MDCコンテキストに設定するキー名を指定します。
install(CallLogging) {
callIdMdc("call-id")
}このキーをロガー設定に渡すことで、ログにコールIDを表示できます。例えば、logback.xml ファイルは次のようになります。
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
<encoder>
<pattern>%d{YYYY-MM-dd HH:mm:ss.SSS} [%thread] %X{call-id} %-5level %logger{36} - %msg%n</pattern>
</encoder>
</appender>完全な例はこちらで確認できます: call-id
