Server Plugin

Ktorサーバーでのリクエストトレース

必要な依存関係: 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を、事前定義された辞書を使用して検証します。コールIDを検証するための独自の条件を提供することもできます。
3. 最後に、特定のヘッダー（例: X-Request-Id）でコールIDをクライアントに送信できます。

CallIdをCallLoggingと組み合わせて使用​​すると、コールIDをMDCコンテキストに配置し、各リクエストのコールIDを表示するようにロガーを構成することで、コールのトラブルシューティングに役立ちます。

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

依存関係の追加

CallIdを使用するには、ビルドスクリプトにktor-server-call-idアーティファクトを含める必要があります。

Gradle (Kotlin)Gradle (Groovy)Maven

CallIdのインストール

アプリケーションにCallIdプラグインをインストールするには、指定された

モジュール

モジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。

内のinstall関数に渡します。以下のコードスニペットは、CallIdをインストールする方法を示しています...

• ... embeddedServer関数呼び出し内で。
• ... Applicationクラスの拡張関数である、明示的に定義されたmodule内で。

embeddedServermodule

CallIdの構成

コールIDの取得

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

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

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

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

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

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

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

コールIDの生成

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

• 以下の例は、事前定義された辞書から特定の長さのコールIDを生成する方法を示しています。

install(CallId) {
    generate(10, "abcde12345")
}

• 以下の例では、generate関数はコールIDを生成するためのブロックを受け入れます。

install(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を取得し、同じヘッダーで送信するために使用できます。

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

完全な例はこちらにあります: call-id。

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

install(CallId) {
    replyToHeader(HttpHeaders.XRequestId)
}

• 必要に応じて、ApplicationCallを使用して、レスポンスでコールIDを送信できます。

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

MDCにコールIDを設定する

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。