Skip to content
Client Plugin

在 Ktor Client 中追蹤請求

必要相依性:io.ktor:ktor-client-call-id

程式碼範例: client-call-id

CallId 外掛程式允許你使用唯一的呼叫 ID 端到端追蹤用戶端請求。這在微服務架構中特別有用,無論請求經過多少個服務,都能持續追蹤呼叫。

呼叫作用域的協同程式上下文(coroutine context)中可能已存在呼叫 ID。預設情況下,該外掛程式會使用目前的上下文來擷取呼叫 ID,並使用 HttpHeaders.XRequestId 標頭將其新增至特定呼叫的上下文中。

此外,若作用域沒有呼叫 ID,你可以設定外掛程式以產生並套用新的呼叫 ID。

在伺服器端,Ktor 提供了 CallId 外掛程式來追蹤用戶端請求。

新增相依性 ​

若要使用 CallId,請將 ktor-client-call-id 構件新增至你的組建指令碼:

kotlin
implementation(ktorLibs.client.callId)
上述程式碼片段使用 Ktor version catalog 來指定 Ktor 相依性。
groovy
implementation ktorLibs.client.callId
上述程式碼片段使用 Ktor version catalog 來指定 Ktor 相依性。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-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.client.plugins.callid.*

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

設定 CallId ​

由 CallIdConfig 類別提供的 CallId 外掛程式配置,允許你產生呼叫 ID 並將其新增至呼叫上下文。

產生呼叫 ID ​

可以透過以下方式之一為特定請求產生呼叫 ID:

  • 預設啟用的 useCoroutineContext 屬性會新增一個產生器,該產生器使用目前的 CoroutineContext 來擷取呼叫 ID。若要停用此功能,請將 useCoroutineContext 設為 false:
kotlin
install(CallId) {
    useCoroutineContext = false
}

在 Ktor 伺服器中,使用 CallId 外掛程式將呼叫 ID 新增至 CoroutineContext。

  • generate() 函式允許你為傳出請求產生呼叫 ID。如果產生呼叫 ID 失敗,它將傳回 null。
kotlin
install(CallId) {
    generate { "call-id-client-2" }
}

你可以使用多種方法來產生呼叫 ID。在這種情況下,將會套用第一個非 null 的值。

新增呼叫 ID ​

擷取到呼叫 ID 後,可以使用以下選項將其新增至請求中:

  • intercept() 函式允許你使用 CallIdInterceptor 將呼叫 ID 新增至請求。
kotlin
install(ClientCallId) {
    intercept { request, callId ->
        request.header(HttpHeaders.XRequestId, callId)
    }
}
  • addToHeader() 函式將呼叫 ID 新增至指定的標頭。它接受標頭作為參數,預設為 HttpHeaders.XRequestId。
kotlin
install(CallId) {
    addToHeader(HttpHeaders.XRequestId)
}

範例 ​

在以下範例中,Ktor 用戶端的 CallId 外掛程式被設定為產生新的呼叫 ID 並將其新增至標頭:

kotlin
val client = HttpClient(CIO) {
    install(CallId) {
        generate { "call-id-client" }
        addToHeader(HttpHeaders.XRequestId)
    }
}

該外掛程式使用協同程式上下文取得呼叫 ID,並利用 generate() 函式產生新的呼叫 ID。接著使用 addToHeader() 函式將第一個非 null 的呼叫 ID 套用至請求標頭。

在 Ktor 伺服器中,隨後可以使用伺服器專用的 CallId 外掛程式中的 retrieve 函式從標頭擷取呼叫 ID。

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

透過這種方式,Ktor 伺服器會擷取請求中指定標頭的 ID,並將其套用至該呼叫的 callId 屬性。

如需完整範例,請參閱 client-call-id