Skip to content
Server Plugin

Ktor Serverでのリクエストの追跡

必要な依存関係: io.ktor:ktor-server-call-id

コード例: call-id

ネイティブサーバーKtorはKotlin/Nativeをサポートしており、追加のランタイムや仮想マシンなしでサーバーを実行できます。のサポート: ✅

CallId プラグインを使用すると、一意のリクエストIDまたはコールIDを使用して、クライアントリクエストをエンドツーエンドで追跡できます。通常、KtorでコールIDを扱う手順は次のようになります。

  1. まず、次のいずれかの方法で特定のリクエストに対するコールIDを取得する必要があります。
    • リバースプロキシ(Nginxなど)やクラウドプロバイダー(Herokuなど)が、X-Request-Id などの特定のヘッダーにコールIDを追加している場合があります。この場合、KtorでコールIDを取得できます。
    • コールIDのないリクエストが届いた場合は、Ktorサーバー上でコールIDを生成できます。
  2. 次に、Ktorは事前定義された辞書を使用して、取得または生成されたコールIDを検証します。独自の検証条件を指定することも可能です。
  3. 最後に、X-Request-Id などの特定のヘッダーを使用して、コールIDをクライアントに送信できます。

CallId を CallLogging と併用すると、コールIDをMDCコンテキストに配置し、各リクエストのコールIDを表示するようにロガーを設定できるため、呼び出しのトラブルシューティングに役立ちます。

クライアント側では、Ktorはクライアントリクエストを追跡するための CallId プラグインを提供しています。

依存関係の追加 ​

CallId を使用するには、ビルドスクリプトに ktor-server-call-id アーティファクトを追加します。

kotlin
implementation(ktorLibs.server.callId)
上記のコードスニペットでは、Ktorバージョンカタログを使用してKtorの依存関係を指定しています。
groovy
implementation ktorLibs.server.callId
上記のコードスニペットでは、Ktorバージョンカタログを使用してKtorの依存関係を指定しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-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.server.plugins.callid.*

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

CallId の設定 ​

コールIDの取得 ​

CallId は、コールIDを取得するためのいくつかの方法を提供しています。

  • 指定したヘッダーからコールIDを取得するには、retrieveFromHeader 関数を使用します。例:

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

    また、header 関数を使用して、同じヘッダーでコールIDを取得および送信することもできます。

  • 必要に応じて、ApplicationCall からコールIDを取得できます。

    kotlin
    install(CallId) {
        retrieve { call ->
            call.request.header(HttpHeaders.XRequestId)
        }
    }

取得されたすべてのコールIDは、デフォルトの辞書を使用して検証される点に注意してください。

コールIDの生成 ​

受信リクエストにコールIDが含まれていない場合は、generate 関数を使用して生成できます。

  • 以下の例は、事前定義された辞書から指定された長さのコールIDを生成する方法を示しています。
    kotlin
    install(CallId) {
        generate(10, "abcde12345")
    }
  • 以下の例では、generate 関数がコールIDを生成するためのブロックを受け取ります。
    kotlin
    install(CallId) {
        val counter = atomic(0)
        generate {
            "generated-call-id-${counter.getAndIncrement()}"
        }
    }

コールIDの検証 ​

取得または生成されたすべてのコールIDは、以下のようなデフォルトの辞書を使用して検証されます。

kotlin
CALL_ID_DEFAULT_DICTIONARY: String = "abcdefghijklmnopqrstuvwxyz0123456789+/=-"

これは、大文字を含むコールIDは検証に失敗することを意味します。必要に応じて、verify 関数を使用してより柔軟なルールを適用できます。

kotlin
install(CallId) {
    verify { callId: String ->
        callId.isNotEmpty()
    }
}

完全な例はこちらで確認できます: call-id

クライアントへのコールIDの送信 ​

コールIDを取得または生成した後、クライアントに送信できます。

  • header 関数を使用すると、コールIDを取得し、同じヘッダーで送信できます。

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

    完全な例はこちらで確認できます: call-id

  • replyToHeader 関数は、指定したヘッダーでコールIDを送信します。

    kotlin
    install(CallId) {
        replyToHeader(HttpHeaders.XRequestId)
    }
  • 必要に応じて、ApplicationCall を使用してレスポンス内でコールIDを送信できます。

    kotlin
    reply { call, callId ->
        call.response.header(HttpHeaders.XRequestId, callId)
    }

コールIDをMDCに設定する ​

CallId を CallLogging と併用すると、コールIDをMDCコンテキストに設定し、各リクエストのコールIDを表示するようにロガーを設定できるため、呼び出しのトラブルシューティングに役立ちます。これを行うには、CallLogging 設定ブロック内で callIdMdc 関数を呼び出し、MDCコンテキストに設定するキー名を指定します。

kotlin
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