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)可能会在特定标头中添加调用 ID,例如 X-Request-Id。在这种情况下,Ktor 允许您检索调用 ID。
    • 否则,如果传入的请求不包含调用 ID,您可以在 Ktor 服务器上生成该 ID。
  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。