在 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。
