Skip to content
Server Plugin

在 Ktor Server 中使用 OpenTelemetry 進行分散式追蹤

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

程式碼範例: opentelemetry

Ktor 與 OpenTelemetry 整合 — 這是一個開源的可觀測性架構,用於收集追蹤 (traces)、指標 (metrics) 和日誌 (logs) 等遙測資料。它提供了檢測應用程式並將資料匯出至 Grafana 或 Jaeger 等監控與可觀測性工具的標準方法。

KtorServerTelemetry 外掛程式可在 Ktor 伺服器應用程式中啟用對傳入 HTTP 請求的分散式追蹤。它會自動建立包含路由、HTTP 方法和狀態碼資訊的 span,從傳入的請求標頭中擷取現有的追蹤上下文,並允許自訂 span 名稱、屬性以及 span 種類。

在用戶端,OpenTelemetry 提供了 KtorClientTelemetry 外掛程式,用於收集傳出至外部服務的 HTTP 呼叫追蹤。

新增相依性 ​

若要使用 KtorServerTelemetry,請將 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 應用程式中安裝 KtorServerTelemetry 外掛程式之前,您需要配置並初始化一個 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
}

程式化配置 ​

若要在程式碼中定義匯出器、處理器 (processors) 和傳播器 (propagators),而不是依賴基於環境的配置,可以使用 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 元件文件。

安裝 KtorServerTelemetry ​

若要將 KtorServerTelemetry 外掛程式安裝到應用程式中,請將其傳遞至指定模組中的 install 函式,並設定已配置的 OpenTelemetry 執行個體:

kotlin
    import io.ktor.server.engine.*
    import io.ktor.server.netty.*
    import io.ktor.server.application.*
    import io.opentelemetry.instrumentation.*

    fun main() {
        embeddedServer(Netty, port = 8080) {
            val openTelemetry = getOpenTelemetry(serviceName = "opentelemetry-ktor-sample-server")

            install(KtorServerTelemetry){
                setOpenTelemetry(openTelemetry)
            }
            // ...
        }.start(wait = true)
    }
kotlin

    import io.ktor.server.application.*
    import io.opentelemetry.instrumentation.*
    // ...

    fun Application.module() {
        val openTelemetry = getOpenTelemetry(serviceName = "opentelemetry-ktor-sample-server")

        install(KtorServerTelemetry){
            setOpenTelemetry(openTelemetry)
        }
        // ...
    }

請確保 KtorServerTelemetry 安裝在任何其他日誌記錄或遙測相關外掛程式之前。

配置追蹤 ​

您可以自訂 Ktor 伺服器記錄與匯出 OpenTelemetry span 的方式。下列選項可讓您調整要追蹤哪些請求、span 如何命名、包含哪些屬性,以及如何判定 span 種類。

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

追蹤其他 HTTP 方法 ​

預設情況下,外掛程式會追蹤標準 HTTP 方法(GET、POST、PUT 等)。若要追蹤其他方法或自訂方法,請配置 knownMethods 屬性:

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

擷取標頭 ​

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

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

選取 span 種類 ​

若要根據請求特性覆寫 span 種類(例如 SERVER、CLIENT、PRODUCER、CONSUMER),請使用 spanKindExtractor 屬性:

kotlin
install(KtorServerTelemetry) {
    // ...
    spanKindExtractor {
        if (httpMethod == HttpMethod.Post) {
            SpanKind.PRODUCER
        } else {
            SpanKind.CLIENT
        }
    }
}

新增自訂屬性 ​

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

kotlin
install(KtorServerTelemetry) {
    // ...
    attributesExtractor {
        onStart {
            attributes.put("start-time", System.currentTimeMillis())
        }
        onEnd {
            attributes.put("end-time", Instant.now().toEpochMilli())
        }
    }
}

其他屬性 ​

若要微調整個應用程式的追蹤行為,您還可以配置其他 OpenTelemetry 屬性,例如傳播器、屬性上限,以及啟用/停用檢測。詳細資訊請參閱 OpenTelemetry Java 配置指南。

使用 Grafana LGTM 驗證遙測資料 ​

若要視覺化並驗證您的遙測資料,您可以將追蹤、指標和日誌匯出到分散式追蹤後端(例如 Grafana)。grafana/otel-lgtm 一體化映像檔組合了 Grafana、Tempo(追蹤)、Loki(日誌)與 Mimir(指標)。

使用 Docker Compose ​

建立包含以下內容的 docker-compose.yml 檔案:

yaml
services:
  grafana-lgtm:
    image: grafana/otel-lgtm:latest
    ports:
      - "4317:4317"   # OTLP gRPC 接收器(追蹤、指標、日誌)
      - "4318:4318"   # OTLP HTTP 接收器
      - "3000:3000"   # Grafana UI
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=admin
    restart: unless-stopped

若要啟動 Grafana LGTM 一體化容器,請執行下列指令:

shell
docker compose up -d

使用 Docker CLI ​

或者,您也可以直接使用 Docker 命令列執行 Grafana:

shell
docker run -d --name grafana_lgtm \
    -p 4317:4317 \   # OTLP gRPC 接收器(追蹤、指標、日誌)
    -p 4318:4318 \   # OTLP HTTP 接收器
    -p 3000:3000 \   # Grafana UI
    -e GF_SECURITY_ADMIN_USER=admin \
    -e GF_SECURITY_ADMIN_PASSWORD=admin \
    grafana/otel-lgtm:latest

應用程式匯出配置 ​

若要將遙測資料從 Ktor 應用程式傳送到 OTLP 端點,請將 OpenTelemetry SDK 配置為使用 gRPC 通訊協定。您可以在建置 SDK 之前透過環境變數設定這些值:

shell
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

或者使用 JVM 旗標:

text
-Dotel.traces.exporter=otlp -Dotel.exporter.otlp.protocol=grpc -Dotel.exporter.otlp.endpoint=http://localhost:4317

存取 Grafana UI ​

啟動後,Grafana UI 將可在 http://localhost:3000/ 存取。

  1. 在 http://localhost:3000/ 開啟 Grafana UI。
  2. 使用預設憑據登入:
    • 使用者:admin
    • 密碼:admin
  3. 在左側導覽功能表中,前往 Drilldown → Traces: Grafana UI Drilldown traces view 進入 Traces 檢視後,您可以:
    • 選取 Rate、Errors 或 Duration 指標。
    • 套用 span 篩選器(例如依服務名稱或 span 名稱)以縮小資料範圍。
    • 檢視追蹤、檢查詳細資訊並與 span 時間軸互動。