Skip to content
Client Plugin

Ktor ClientでのOpenTelemetryによる分散トレーシング

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

コード例: opentelemetry

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

KtorClientTelemetry プラグインを使用すると、送信HTTPリクエストを自動的にトレースできます。メソッド、URL、ステータスコードなどのメタデータをキャプチャし、サービス間でトレースコンテキストを伝播します。また、スパン属性をカスタマイズしたり、独自のOpenTelemetry構成を使用したりすることもできます。

サーバー側では、OpenTelemetryはサーバーへの受信HTTPリクエストを計装するための KtorServerTelemetry プラグインを提供しています。

依存関係の追加 ​

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

自動検出された構成をカスタマイズすることも可能です。たとえば、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 components のドキュメントを参照してください。

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)
    }
}

トレーシングの構成 ​

送信HTTP呼び出しに対してKtorクライアントがOpenTelemetryスパンを記録およびエクスポートする方法をカスタマイズできます。以下のオプションを使用して、どのリクエストをトレースするか、スパンにどのように名前を付けるか、どのような属性を含めるか、どのヘッダーをキャプチャするか、スパン種別(kind)をどのように決定するかを調整できます。

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

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

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

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

ヘッダーのキャプチャ ​

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

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

レスポンスヘッダーのキャプチャ ​

特定のHTTPレスポンスヘッダーをスパン属性としてキャプチャするには、capturedResponseHeaders プロパティを使用します。

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

カスタム属性の追加 ​

スパンの開始時または終了時にカスタム属性を付加するには、attributesExtractor プロパティを使用します。

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

次のステップ ​

KtorClientTelemetry のインストールと構成が完了したら、KtorServerTelemetry を使用しているサービスなど、テレメトリが有効になっているサービスにリクエストを送信することで、スパンが作成されて伝播していることを確認できます。Jaeger、Zipkin、または Grafana Tempo などのオブザーバビリティバックエンドでトレースの両側を確認することで、分散トレーシングがエンドツーエンドで機能していることを確認できます。