在 Ktor Client 中使用 OpenTelemetry 進行分散式追蹤
必要的相依性:io.opentelemetry.instrumentation:opentelemetry-ktor-3.0
程式碼範例: opentelemetry
Ktor 與 OpenTelemetry 整合——這是一個開源的可觀測性架構,用於收集追蹤(traces)、指標(metrics)和記錄(logs)等遙測資料。它提供了一種標準方法來檢測(instrument)應用程式,並將資料匯出到 Grafana 或 Jaeger 等監控與可觀測性工具。
KtorClientTelemetry 外掛程式可讓您自動追蹤傳出的 HTTP 請求。它會擷取方法、URL 和狀態碼等元資料,並跨服務傳播追蹤上下文。您還可以自訂 span 屬性或使用自己的 OpenTelemetry 配置。
在伺服器端,OpenTelemetry 提供了 KtorServerTelemetry 外掛程式,用於檢測傳入伺服器的 HTTP 請求。
新增相依性
若要使用 KtorClientTelemetry,請將 opentelemetry-ktor-3.0 構件新增至您的組建指令碼中:
implementation("io.opentelemetry.instrumentation:opentelemetry-ktor-3.0:2.18.1-alpha")implementation "io.opentelemetry.instrumentation:opentelemetry-ktor-3.0:2.18.1-alpha" <dependencies>
<dependency>
<groupId>io.opentelemetry.instrumentation</groupId>
<artifactId>opentelemetry-ktor-3.0</artifactId>
<version>2.18.1-alpha</version>
</dependency>
</dependencies>配置 OpenTelemetry
在 Ktor 應用程式中安裝 KtorClientTelemetry 外掛程式之前,您需要配置並初始化一個 OpenTelemetry 執行個體。該執行個體負責管理遙測資料,包括追蹤和指標。
自動配置
配置 OpenTelemetry 的常見方法是使用 AutoConfiguredOpenTelemetrySdk。這會根據系統屬性與環境變數自動配置匯出器(exporters)和資源,從而簡化設定流程。
您仍然可以自訂自動偵測到的配置——例如,新增 service.name 資源屬性:
package com.example
import io.opentelemetry.api.OpenTelemetry
import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk
import io.opentelemetry.semconv.ServiceAttributes
fun getOpenTelemetry(serviceName: String): OpenTelemetry {
return AutoConfiguredOpenTelemetrySdk.builder().addResourceCustomizer { oldResource, _ ->
oldResource.toBuilder()
.putAll(oldResource.attributes)
.put(ServiceAttributes.SERVICE_NAME, serviceName)
.build()
}.build().openTelemetrySdk
}程式化配置
若要在程式碼中定義匯出器、處理器和傳播器,而不是依賴基於環境的配置,可以使用 OpenTelemetrySdk。
以下範例展示如何以程式化方式配置帶有 OTLP 匯出器、span 處理器和追蹤上下文傳播器的 OpenTelemetry:
import io.opentelemetry.api.OpenTelemetry
import io.opentelemetry.api.trace.propagation.W3CTraceContextPropagator
import io.opentelemetry.context.propagation.ContextPropagators
import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter
import io.opentelemetry.sdk.OpenTelemetrySdk
import io.opentelemetry.sdk.trace.SdkTracerProvider
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor
fun configureOpenTelemetry(): OpenTelemetry {
val spanExporter = OtlpGrpcSpanExporter.builder()
.setEndpoint("http://localhost:4317")
.build()
val tracerProvider = SdkTracerProvider.builder()
.addSpanProcessor(BatchSpanProcessor.builder(spanExporter).build())
.build()
return OpenTelemetrySdk.builder()
.setTracerProvider(tracerProvider)
.setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance()))
.buildAndRegisterGlobal()
}如果您需要完全控制遙測設定,或者部署環境無法依賴自動配置時,請使用此方法。
若要了解更多資訊,請參閱 OpenTelemetry SDK 元件文件。
安裝 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 類型(span kinds)。
若要了解有關這些概念的更多資訊,請參閱 OpenTelemetry 追蹤文件。
追蹤其他 HTTP 方法
預設情況下,該外掛程式會追蹤標準 HTTP 方法(GET、POST、PUT 等)。若要追蹤其他或自訂方法,請配置 knownMethods 屬性:
install(KtorClientTelemetry) {
// ...
knownMethods(HttpMethod.DefaultMethods + CUSTOM_METHOD)
}擷取標頭
若要將特定的 HTTP 請求標頭納入為 span 屬性,請使用 capturedRequestHeaders 屬性:
install(KtorClientTelemetry) {
// ...
capturedRequestHeaders(HttpHeaders.UserAgent)
}擷取回應標頭
若要將特定的 HTTP 回應標頭擷取為 span 屬性,請使用 capturedResponseHeaders 屬性:
install(KtorClientTelemetry) {
// ...
capturedResponseHeaders(HttpHeaders.ContentType, CUSTOM_HEADER)
}新增自訂屬性
若要在 span 的開始或結束時附加自訂屬性,請使用 attributesExtractor 屬性:
install(KtorClientTelemetry) {
// ...
attributesExtractor {
onStart {
attributes.put("start-time", System.currentTimeMillis())
}
onEnd {
attributes.put("end-time", Instant.now().toEpochMilli())
}
}
}後續步驟
安裝並配置好 KtorClientTelemetry 之後,您可以透過向同樣啟用了遙測的服務(例如使用 KtorServerTelemetry 的服務)發送請求,來驗證 span 是否正確建立並傳播。在 Jaeger、Zipkin 或 Grafana Tempo 等可觀測性後端中查看追蹤的兩端,即可確認分散式追蹤是否正常進行端到端運作。
