Skip to content
Server Plugin

Ktor Server における OpenTelemetry を使用した分散トレーシング

必要な依存関係: io.opentelemetry.instrumentation:opentelemetry-ktor-3.0

コード例: opentelemetry

Ktor は、トレース、メトリクス、ログなどのテレメトリデータを収集するためのオープンソースのオブザーバビリティフレームワークである OpenTelemetry と統合されています。アプリケーションのインストルメンテーションを行い、Grafana や Jaeger などの監視・オブザーバビリティツールにデータをエクスポートする標準的な方法を提供します。

KtorServerTelemetry プラグインは、Ktor サーバーアプリケーションにおける受信 HTTP リクエストの分散トレーシングを可能にします。ルート、HTTP メソッド、ステータスコード情報を含む スパン(span) を自動的に作成し、受信リクエストヘッダーから既存のトレースコンテキストを抽出し、スパン名、属性、スパンの種類(kind)をカスタマイズできるようにします。

クライアント側では、外部サービスへの送信 HTTP 呼び出しのトレースを収集する KtorClientTelemetry プラグインが OpenTelemetry によって提供されています。

依存関係の追加 ​

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 を使用することです。これにより、システムプロパティや環境変数に基づいてエクスポーターとリソースが自動的に構成され、セットアップが簡素化されます。

自動検出された設定は引き続きカスタマイズできます。例えば、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 エクスポーター、スパンプロセッサー、およびトレースコンテキストプロパゲーターを使用して、プログラムで 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 スパンをどのように記録およびエクスポートするかをカスタマイズできます。以下のオプションを使用して、どのリクエストをトレースするか、スパンをどのように命名するか、どのような属性を含めるか、スパンの種類をどのように決定するかを調整できます。

これらの概念の詳細については、OpenTelemetry トレーシングドキュメントを参照してください。

追加の HTTP メソッドのトレース ​

デフォルトでは、このプラグインは標準の HTTP メソッド(GET、POST、PUT など)をトレースします。追加のメソッドやカスタムメソッドをトレースするには、knownMethods プロパティを設定します:

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

ヘッダーのキャプチャ ​

特定の HTTP リクエストヘッダーをスパン属性として含めるには、capturedRequestHeaders プロパティを使用します:

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

スパンの種類(Span kind)の選択 ​

リクエストの特性に基づいてスパンの種類(SERVER、CLIENT、PRODUCER、CONSUMER など)をオーバーライドするには、spanKindExtractor プロパティを使用します:

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

カスタム属性の追加 ​

スパンの開始時または終了時にカスタム属性を付与するには、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 receiver (traces, metrics, logs)
      - "4318:4318"   # OTLP HTTP receiver
      - "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 receiver (traces, metrics, logs)
    -p 4318:4318 \   # OTLP HTTP receiver
    -p 3000:3000 \   # Grafana UI
    -e GF_SECURITY_ADMIN_USER=admin \
    -e GF_SECURITY_ADMIN_PASSWORD=admin \
    grafana/otel-lgtm:latest

アプリケーションのエクスポート設定 ​

Ktor アプリケーションから OTLP エンドポイントにテレメトリを送信するには、gRPC プロトコルを使用するように OpenTelemetry SDK を設定します。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. デフォルトの認証情報でログインします:
    • User:admin
    • Password:admin
  3. 左側のナビゲーションメニューで、Drilldown → Traces に移動します: Grafana UI Drilldown traces viewTraces ビューに入ると、次の操作が可能です:
    • Rate(レート)、Errors(エラー)、または Duration(所要時間)メトリクスを選択する。
    • スパンフィルター(サービス名やスパン名など)を適用してデータを絞り込む。
    • トレースの表示、詳細の確認、スパンタイムラインの操作を行う。