在 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 工件添加到构建脚本中:
安装 CallId
要将 CallId 插件安装到应用程序中, 请将其传递给指定模块模块允许您通过对路由进行分组来构建应用程序结构。中的 install 函数。 以下示例展示了如何安装 CallId:
- 在
embeddedServer()函数调用中。 - 在
Application类上显式定义的module()扩展函数中。
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)
}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:
install(CallId) {
useCoroutineContext = false
}在 Ktor 服务器中,使用 CallId 插件将调用 ID 添加到 CoroutineContext 中。
generate()函数允许你为传出请求生成调用 ID。如果生成调用 ID 失败,它将返回null。
install(CallId) {
generate { "call-id-client-2" }
}你可以使用多种方式来生成调用 ID。这样,第一个非 null 值将被应用。
添加调用 ID
检索到调用 ID 后,你可以使用以下选项将其添加到请求中:
intercept()函数允许你使用CallIdInterceptor将调用 ID 添加到请求中。
install(ClientCallId) {
intercept { request, callId ->
request.header(HttpHeaders.XRequestId, callId)
}
}addToHeader()函数将调用 ID 添加到指定的标头中。它接受一个标头作为形参,默认值为HttpHeaders.XRequestId。
install(CallId) {
addToHeader(HttpHeaders.XRequestId)
}示例
在以下示例中,Ktor 客户端的 CallId 插件配置为生成新的调用 ID 并将其添加到标头:
val client = HttpClient(CIO) {
install(CallId) {
generate { "call-id-client" }
addToHeader(HttpHeaders.XRequestId)
}
}该插件使用协程上下文获取调用 ID,并利用 generate() 函数生成新的调用 ID。然后通过 addToHeader() 函数将第一个非 null 的调用 ID 应用到请求标头中。
在 Ktor 服务器中,随后可以使用服务器端的 CallId 插件中的 retrieve 函数从标头中检索调用 ID。
install(CallId) {
retrieveFromHeader(HttpHeaders.XRequestId)
}通过这种方式,Ktor 服务器检索请求指定标头的 ID,并将其应用到调用的 callId 属性中。
有关完整示例,请参阅 client-call-id
