Client Plugin

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

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

コード例: opentelemetry

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

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

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

undefined undefined

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

トレーシングの設定

Ktor クライアントが送信 HTTP コールの OpenTelemetry スパンを記録およびエクスポートする方法をカスタマイズできます。以下のオプションを使用して、どのリクエストをトレースするか、スパンの名前、含まれる属性、キャプチャされるヘッダー、およびスパンの種類（kind）の決定方法を調整できます。

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

undefined undefined

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

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

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

undefined

次のステップ

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