Server Plugin

Ktor Server でのリクエストのトレース

必須の依存関係: io.ktor:ktor-server-call-id

コード例: call-id

Native サーバー

Ktor supports Kotlin/Native and allows you to run a server without an additional runtime or virtual machine.

のサポート: ✅

CallId プラグインを使用すると、一意のリクエスト ID またはコール ID を使用して、クライアントリクエストをエンドツーエンド (end-to-end) でトレースできます。通常、Ktor でコール ID を操作する流れは次のようになります。

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

CallId を CallLogging と併用すると、コール ID を MDC コンテキスト (MDC context) に配置し、各リクエストに対してコール ID を表示するようにロガーを設定することで、トラブルシューティングに役立てることができます。

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

依存関係の追加

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

Gradle (Kotlin)Gradle (Groovy)Maven

CallId のインストール

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

モジュール

Modules allow you to structure your application by grouping routes.

内で 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