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 伺服器端產生它。
  2. 接下來,Ktor 會使用預先定義的字典驗證擷取或產生的呼叫 ID。您也可以提供自訂條件來驗證呼叫 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。