Skip to content
Client Plugin

在 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 構件新增至您的組建指令碼中:

kotlin
implementation("io.opentelemetry.instrumentation:opentelemetry-ktor-3.0:2.18.1-alpha")
groovy
implementation "io.opentelemetry.instrumentation:opentelemetry-ktor-3.0:2.18.1-alpha"
xml
 <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 資源屬性:

kotlin
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:

kotlin
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 執行個體:

kotlin
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 屬性:

kotlin
install(KtorClientTelemetry) {
    // ...
    knownMethods(HttpMethod.DefaultMethods + CUSTOM_METHOD)
}

擷取標頭 ​

若要將特定的 HTTP 請求標頭納入為 span 屬性,請使用 capturedRequestHeaders 屬性:

kotlin
install(KtorClientTelemetry) {
    // ...
    capturedRequestHeaders(HttpHeaders.UserAgent)
}

擷取回應標頭 ​

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

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

新增自訂屬性 ​

若要在 span 的開始或結束時附加自訂屬性,請使用 attributesExtractor 屬性:

kotlin
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 等可觀測性後端中查看追蹤的兩端,即可確認分散式追蹤是否正常進行端到端運作。