在 Ktor Server 中跟踪请求
所需依赖项:io.ktor:ktor-server-call-id
代码示例: call-id
原生服务器Ktor 支持 Kotlin/Native,并允许您在无需额外运行时或虚拟机的情况下运行服务器。支持:✅
CallId 插件允许您通过使用唯一的请求 ID 或调用 ID 端到端跟踪客户端请求。通常,在 Ktor 中使用调用 ID 的流程如下:
- 首先,您需要通过以下方式之一获取特定请求的调用 ID:
- 接下来,Ktor 会使用预定义的字典验证检索到的/生成的调用 ID。您还可以提供自己的条件来验证调用 ID。
- 最后,您可以在特定标头(例如
X-Request-Id)中将调用 ID 发送给客户端。
将 CallId 与 CallLogging 结合使用,可通过将调用 ID 放入 MDC 上下文并配置日志记录器以显示每个请求的调用 ID,从而帮助您对调用进行故障排除。
在客户端,Ktor 提供了 CallId 插件来跟踪客户端请求。
添加依赖项
要使用 CallId,请将 ktor-server-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.server.plugins.callid.*
fun main() {
embeddedServer(Netty, port = 8080) {
install(CallId)
// ...
}.start(wait = true)
}import io.ktor.server.application.*
import io.ktor.server.plugins.callid.*
// ...
fun Application.module() {
install(CallId)
// ...
}配置 CallId
检索调用 ID
CallId 提供了多种检索调用 ID 的方法:
要从指定的标头中检索调用 ID,请使用
retrieveFromHeader函数,例如:kotlininstall(CallId) { retrieveFromHeader(HttpHeaders.XRequestId) }您还可以使用
header函数在同一标头中检索并发送调用 ID。如有需要,您可以从
ApplicationCall中检索调用 ID:kotlininstall(CallId) { retrieve { call -> call.request.header(HttpHeaders.XRequestId) } }
请注意,所有检索到的调用 ID 都会使用默认字典进行验证。
生成调用 ID
如果传入的请求不包含调用 ID,您可以使用 generate 函数生成它:
- 以下示例演示了如何从预定义字典中生成具有特定长度的调用 ID:kotlin
install(CallId) { generate(10, "abcde12345") } - 在以下示例中,
generate函数接受一个用于生成调用 ID 的代码块:kotlininstall(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
header函数可用于检索调用 ID并在同一标头中发送它:kotlininstall(CallId) { header(HttpHeaders.XRequestId) }您可以在此处找到完整示例:call-id。
replyToHeader函数在指定的标头中发送调用 ID:kotlininstall(CallId) { replyToHeader(HttpHeaders.XRequestId) }如有需要,您可以使用
ApplicationCall在响应中发送调用 ID:kotlinreply { call, callId -> call.response.header(HttpHeaders.XRequestId, callId) }
将调用 ID 放入 MDC
将 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。
