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プラグインを提供します。

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スパンをどのように記録し、エクスポートするかをカスタマイズできます。以下のオプションを使用すると、どのリクエストをトレースするか、スパンにどのように名前を付けるか、どのような属性が含まれるか、どのヘッダーをキャプチャするか、スパンの種類をどのように決定するかを調整できます。

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

レスポンスヘッダーをキャプチャする

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

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

次のステップ

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