Skip to content
Client Plugin

在 Ktor Client 中跟踪请求

必需依赖项: io.ktor:ktor-client-call-id

代码示例: client-call-id

CallId 插件允许你通过使用唯一的调用 ID 来端到端跟踪客户端请求。这在微服务架构中尤为有用,无论请求经过多少个服务,都可以对调用保持跟踪。

调用作用域的协程上下文中可能已经包含了一个调用 ID。默认情况下,该插件使用当前上下文来检索调用 ID,并使用 HttpHeaders.XRequestId 标头将其添加到具体调用的上下文中。

此外,如果作用域未附带调用 ID,你可以配置该插件以生成并应用新的调用 ID。

在服务器端,Ktor 提供了 CallId 插件用于跟踪客户端请求。

添加依赖项 ​

要使用 CallId,请将 ktor-client-call-id 工件添加到构建脚本中:

kotlin
implementation(ktorLibs.client.callId)
上述代码段使用 Ktor 版本目录 来指定 Ktor 依赖项。
groovy
implementation ktorLibs.client.callId
上述代码段使用 Ktor 版本目录 来指定 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