Client Plugin

在 Ktor 用戶端使用 OpenTelemetry 進行分散式追蹤

必要相依性：io.opentelemetry.instrumentation:opentelemetry-ktor-3.0

程式碼範例： opentelemetry

Ktor 與 OpenTelemetry 整合 — 這是一個開源的可觀測性框架，用於收集追蹤 (traces)、指標 (metrics) 和記錄 (logs) 等遙測資料。它提供了一種標準化的方式來對應用程式進行檢測，並將資料匯出到 Grafana 或 Jaeger 等監控與可觀測性工具。

KtorClientTelemetry 外掛程式可讓您自動追蹤傳出的 HTTP 請求。它會擷取方法 (method)、URL 和狀態碼等元資料，並在服務之間傳遞追蹤上下文。您還可以自訂 span 屬性或使用自己的 OpenTelemetry 配置。

在伺服器端，OpenTelemetry 提供了 KtorServerTelemetry 外掛程式，用於對進入伺服器的 HTTP 請求進行檢測。

安裝 KtorClientTelemetry

要安裝 KtorClientTelemetry 外掛程式，請將其傳遞給 用戶端配置區塊 內的 install 函式，並設定 已配置的 OpenTelemetry 執行個體：

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.auth.*
//...

val client = HttpClient(CIO) {
    val openTelemetry = getOpenTelemetry(serviceName = "opentelemetry-ktor-client")

    install(KtorClientTelemetry) {
        setOpenTelemetry(openTelemetry)
    }
}

配置追蹤

您可以自訂 Ktor 用戶端如何記錄和匯出傳出 HTTP 呼叫的 OpenTelemetry span。以下選項允許您調整哪些請求被追蹤、span 如何命名、它們包含哪些屬性、擷取哪些標頭，以及如何決定 span 類型。

如需有關這些概念的更多資訊，請參閱 OpenTelemetry 追蹤文件。

擷取回應標頭

若要將特定的 HTTP 回應標頭擷取為 span 屬性，請使用 capturedResponseHeaders 屬性：

install(KtorClientTelemetry) {
    // ...
    capturedResponseHeaders(HttpHeaders.ContentType, CUSTOM_HEADER)
}

後續步驟

安裝並配置好 KtorClientTelemetry 後，您可以透過向同樣啟用了遙測功能的服務（例如使用 KtorServerTelemetry 的服務）發送請求，來驗證 span 是否正在建立和傳遞。在 Jaeger、Zipkin 或 Grafana Tempo 等可觀測性後端查看追蹤的兩端，即可確認分散式追蹤是否正在端到端運作。