クライアント側トレースでパフォーマンスをモニタリングする
Firestore リクエストをエンドツーエンドでモニタリングおよびデバッグするには、Java クライアント ライブラリでトレースを有効にします。クライアント側のトレースにより、アプリケーションで発生しているパフォーマンスに関するシグナルだけでなく、問題のデバッグに役立つ分析情報も得られます。
クライアントから RPC を実行して収集されるクライアント側のトレースには、次の情報が表示されます。
- クライアントが RPC リクエストを送信した時刻とクライアントが RPC レスポンスを受信した時刻のタイムスタンプ（ネットワークおよびクライアント システムにより生じるレイテンシを含む）
- クライアントとその構成に関する情報を表示する属性（Key-Value ペア）
- スパン内のキーイベントに関連付けられたログ
- クライアントでクラッシュが発生した場合のスタック トレース
OpenTelemetry
Java クライアント ライブラリのトレースは、OpenTelemetry API を使用してインストゥルメント化されます。OpenTelemetry は、業界標準のオープンソースのオブザーバビリティ フレームワークです。OpenTelemetry は、インストルメンテーション API と SDK、コレクタ、バックエンド固有のエクスポータ、柔軟な構成オプション（サンプリング制御、スパン制限など）などの幅広いツールを提供します。
エクスポータとコレクタを使用してトレースをエクスポートする
構成の一環として、トレースをオブザーバビリティ バックエンドにエクスポートできます。Cloud Trace など、ほとんどのオブザーバビリティ サービス プロバイダは、使用するエクスポータを提供しています。
OpenTelemetry では、エクスポータに加えて、Collector を設定することをおすすめします。Collector により、サービスがデータを迅速にオフロードできるようになります。また、Collector が再試行、バッチ処理、暗号化などの追加処理を行うことができます。Collector はアプリケーションとともに実行されます。Collector は OTLP メッセージを受信して処理し、オブザーバビリティ バックエンドにエクスポートします。
制限事項
クライアント側のトレースには次の制限があります。
- トレーススパンは Java クライアント ライブラリで使用できます。
- クライアント ライブラリは、リアルタイム リスナーのトレーススパンを生成しません。
課金
Firestore の使用に加えて、クライアント側のトレースには料金が発生する場合があります。
OpenTelemetry フレームワークのトレース収集や使用量は無料です。
オブザーバビリティ バックエンドへのトレーススパンの取り込みは課金対象になる場合があります。たとえば、Cloud Trace をバックエンドとして使用する場合は、Cloud Trace の料金に従って課金されます。別のオブザーバビリティ サービス プロバイダを使用する場合は、その課金モデルと関連する費用を確認します。
課金について理解を深めるには、トラフィックに基づいて小さなトレース サンプリング率（RPC の一部をトレースする）から始めます。
始める前に
始める前に:
必要な Identity and Access Management のロールを使用して、アプリがオブザーバビリティ バックエンドにトレースを書き込むサービス アカウントを設定してください。
トレース オペレーション IAM ロール トレースを読み取る roles/cloudtrace.userトレースを書き込む roles/cloudtrace.agent読み取り/書き込みトレース roles/cloudtrace.adminこのプロジェクトで Trace API が有効になっていることを確認します。
クライアント側トレースを構成する
このセクションでは、クライアント側トレースの構成例について説明します。Collector にエクスポートすることも、オブザーバビリティ バックエンドに直接エクスポートすることもできます。クライアント側のトレースを構成する次のオプションも使用できます。
- OpenTelemetry API を使用してトレースを構成できます。そのためには、アプリケーションのコードを変更する必要があります。次の例をご覧ください。
- 自動エージェントを使用すると、コードを変更せずにトレースを構成できます。環境変数
FIRESTORE_ENABLE_TRACING=ONを設定する必要があります。また、エージェントの設定で説明されているように、その他の構成設定も設定する必要があります。次の例をご覧ください。
OpenTelemetry API を使用してトレースを Collector にエクスポートする
次のコードでは、サンプリング率 10% のスパンを OpenTelemetry Collector にエクスポートするように、Firestore Java クライアント ライブラリを構成します。
Java（管理）
Resource resource = Resource
.getDefault().merge(Resource.builder().put(SERVICE_NAME, "My App").build());
OtlpGrpcSpanExporter otlpGrpcSpanExporter =
OtlpGrpcSpanExporter
.builder()
.setEndpoint("http://localhost:4317") // Replace with your OTLP endpoint
.build();
// Using a batch span processor
// You can also use other `BatchSpanProcessorBuilder` methods
// to further customize.
BatchSpanProcessor otlpGrpcSpanProcessor =
BatchSpanProcessor.builder(otlpGrpcSpanExporter).build();
// Export to a collector that is expecting OTLP using gRPC.
OpenTelemetrySdk otel = OpenTelemetrySdk.builder()
.setTracerProvider(
SdkTracerProvider.builder()
.setResource(resource)
.addSpanProcessor(otlpGrpcSpanProcessor)
.setSampler(Sampler.traceIdRatioBased(0.1))
.build())
.build();
Firestore firestore = FirestoreOptions
.newBuilder()
.setOpenTelemetryOptions(
FirestoreOpenTelemetryOptions.newBuilder()
.setTracingEnabled(true)
.setOpenTelemetry(otel)
.build())
.build().getService();
OpenTelemetry API を使用してオブザーバビリティ バックエンドに直接エクスポートする
次のコードでは、トレース サンプリング率 10% でトレーススパンを Cloud Trace に直接エクスポートするように Java クライアント ライブラリを構成しています。他のオブザーバビリティ サービス プロバイダのエクスポータを使用して、バックエンドに直接エクスポートできます。オブザーバビリティ バックエンドが OTLP 取り込みをサポートしている場合は、カスタム エクスポータを使用する代わりに、OpenTelemetry OtlpGrpcSpanExporter を使用してバックエンドにエクスポートできます。
Java（管理）
// TraceExporter needed for this use case
import com.google.cloud.opentelemetry.trace.TraceExporter;
Resource resource = Resource
.getDefault().merge(Resource.builder().put(SERVICE_NAME, "My App").build());
SpanExporter gcpTraceExporter = TraceExporter.createWithDefaultConfiguration();
// Using a batch span processor
// You can also use other `BatchSpanProcessorBuilder` methods
// to further customize.
SpanProcessor gcpBatchSpanProcessor =
BatchSpanProcessor.builder(gcpTraceExporter).build();
// Export directly to Cloud Trace with 10% trace sampling ratio
OpenTelemetrySdk otel = OpenTelemetrySdk.builder()
.setTracerProvider(SdkTracerProvider.builder()
.setResource(resource)
.addSpanProcessor(gcpBatchSpanProcessor)
.setSampler(Sampler.traceIdRatioBased(0.1))
.build())
.build();
Firestore firestore = FirestoreOptions
.newBuilder()
.setOpenTelemetryOptions(
FirestoreOpenTelemetryOptions.newBuilder()
.setTracingEnabled(true)
.setOpenTelemetry(otel)
.build())
.build().getService();
自動エージェントを使用した Collector へのエクスポート
OTLP gRPC レシーバーを有効にして OpenTelemetry Collector を実行する。エージェントのエクスポータを otlp に設定し、エージェントがデータをエクスポートするエンドポイントを指定します。次の例では、10% のサンプリング率を使用し、localhost ポート 4317 をリッスンする Collector にトレースを送信します。
ターミナル
FIRESTORE_ENABLE_TRACING=ON \
java \
-javaagent:path/to/opentelemetry-javaagent.jar \
-Dotel.traces.exporter=otlp \
-Dotel.exporter.otlp.endpoint="http://localhost:4317" \
-Dotel.traces.sampler=traceidratio \
-Dotel.traces.sampler.arg=0.1 \
-Dotel.service.name="My App" \
-jar myapp.jar
自動エージェントを使用してオブザーバビリティ バックエンドに直接エクスポートする
環境変数 FIRESTORE_ENABLE_TRACING=ON を設定するだけでなく、特定のバックエンドに OpenTelemetry Java エージェント拡張機能を追加する必要があります。次の例では、Trace エクスポータ拡張機能と 10% のトレース サンプリング率を使用します。
ターミナル
FIRESTORE_ENABLE_TRACING=ON \
java \
-javaagent:path/to/opentelemetry-javaagent.jar \
-Dotel.javaagent.extensions=/path/to/exporter-auto-0.26.0-alpha-shaded.jar \
-Dotel.traces.exporter=google_cloud_trace \
-Dotel.traces.sampler=traceidratio \
-Dotel.traces.sampler.arg=0.1 \
トレースの例
次の例は、Cloud Trace でトレース情報がどのように表示されるかを示しています。使用可能な属性と値の詳細については、トレーススパンの属性とイベントをご覧ください。
トレーススパンの例
イベントログの例
属性値の例
スタック トレースと例外イベントの例
次のステップ
- トレーススパンの属性とイベントのリファレンスを参照する
- サーバー側のモニタリングについて学習する。