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 アーティファクトを追加します。
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 を使用することです。これにより、システムプロパティや環境変数に基づいてエクスポーターとリソースが自動的に構成され、セットアップが簡素化されます。
自動検出された構成をカスタマイズすることも可能です。たとえば、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エクスポーター、スパンプロセッサー、およびトレースコンテキストプロパゲーターを使用して、プログラムで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 components のドキュメントを参照してください。
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)
}
}トレーシングの構成
送信HTTP呼び出しに対してKtorクライアントがOpenTelemetryスパンを記録およびエクスポートする方法をカスタマイズできます。以下のオプションを使用して、どのリクエストをトレースするか、スパンにどのように名前を付けるか、どのような属性を含めるか、どのヘッダーをキャプチャするか、スパン種別(kind)をどのように決定するかを調整できます。
これらの概念の詳細については、OpenTelemetry tracing のドキュメントを参照してください。
追加のHTTPメソッドのトレース
デフォルトでは、プラグインは標準のHTTPメソッド(GET、POST、PUT など)をトレースします。追加のメソッドやカスタムメソッドをトレースするには、knownMethods プロパティを構成します。
install(KtorClientTelemetry) {
// ...
knownMethods(HttpMethod.DefaultMethods + CUSTOM_METHOD)
}ヘッダーのキャプチャ
特定のHTTPリクエストヘッダーをスパン属性として含めるには、capturedRequestHeaders プロパティを使用します。
install(KtorClientTelemetry) {
// ...
capturedRequestHeaders(HttpHeaders.UserAgent)
}レスポンスヘッダーのキャプチャ
特定のHTTPレスポンスヘッダーをスパン属性としてキャプチャするには、capturedResponseHeaders プロパティを使用します。
install(KtorClientTelemetry) {
// ...
capturedResponseHeaders(HttpHeaders.ContentType, CUSTOM_HEADER)
}カスタム属性の追加
スパンの開始時または終了時にカスタム属性を付加するには、attributesExtractor プロパティを使用します。
install(KtorClientTelemetry) {
// ...
attributesExtractor {
onStart {
attributes.put("start-time", System.currentTimeMillis())
}
onEnd {
attributes.put("end-time", Instant.now().toEpochMilli())
}
}
}次のステップ
KtorClientTelemetry のインストールと構成が完了したら、KtorServerTelemetry を使用しているサービスなど、テレメトリが有効になっているサービスにリクエストを送信することで、スパンが作成されて伝播していることを確認できます。Jaeger、Zipkin、または Grafana Tempo などのオブザーバビリティバックエンドでトレースの両側を確認することで、分散トレーシングがエンドツーエンドで機能していることを確認できます。
