Datastore モードの Firestore（Datastore）リクエストをエンドツーエンドでモニタリングしてデバッグするには、Java クライアント ライブラリでトレースを有効にします。クライアントサイドのトレースでは、アプリケーションで発生したパフォーマンスに関するシグナルと、問題のデバッグに役立つ分析情報を提供できます。
クライアントサイドのトレースでは、クライアントからの RPC の実行によって収集され、次の情報を提供します。
- クライアントが RPC リクエストを送信した時点やクライアントが RPC レスポンスを受信した時点のタイムスタンプを含むスパンで、ネットワークとクライアント システムによって発生したレイテンシが含まれます。
- クライアントとその構成に関する情報を表示する属性（Key-Value ペア）。
- スパンのキーイベントに関連付けられたログ。
- クライアントでクラッシュが発生した場合のスタック トレース。
OpenTelemetry
Java クライアント ライブラリのトレースは、OpenTelemetry API を使用して計測されます。OpenTelemetry は、業界標準のオープンソース化されたオブザーバビリティ フレームワークです。OpenTelemetry には、計測 API や SDK、コレクタ、バックエンド固有のエクスポータ、サンプリング制御やスパンの上限などの柔軟な構成オプションなど、幅広いツールが用意されています。
エクスポータとコレクタを使用してトレースをエクスポートする
構成の一環として、トレースをオブザーバビリティ バックエンドにエクスポートできます。ほとんどのオブザーバビリティ サービス プロバイダは、Cloud Trace など、使用できるエクスポータを用意しています。
OpenTelemetry では、エクスポータに加えて、Collector を設定することをおすすめします。Collector により、サービスがデータを迅速にオフロードできるようになります。また、Collector が再試行、バッチ処理、暗号化などの追加処理を行うことができます。Collector はアプリケーションとともに実行されます。コレクタは OpenTelemetry Protocol（OTLP）メッセージを受信して処理し、オブザーバビリティ バックエンドにエクスポートします。
制限事項
トレーススパンは、Java クライアント ライブラリでのみ使用できます。
お支払い
クライアントサイド トレースを行うと、Datastore の使用量に加えて費用が発生する場合があります。
トレースの収集や OpenTelemetry フレームワークの使用に対して料金は発生しません。
トレーススパンのオブザーバビリティ バックエンドへの取り込みに料金が発生する可能性があります。たとえば、バックエンドとして Cloud Trace を使用する場合は、Cloud Trace の料金に沿って課金されます。別のオブザーバビリティ サービス プロバイダを使用している場合は、その課金モデルと関連費用を確認します。
課金について把握するには、トラフィックに基づいて小さなトレース サンプリング比率（RPC の一部をトレース）から始めます。
始める前に
始める前に:
アプリがオブザーバビリティ バックエンドにトレースを書き込むサービス アカウントに、必要な Identity and Access Management ロールが設定されていることを確認します。
トレース オペレーション IAM ロール トレースを読み取る roles/cloudtrace.userトレースに書き込む roles/cloudtrace.agent読み取り/書き込みトレース roles/cloudtrace.adminこのプロジェクトで Trace API が有効になっていることを確認します。
クライアント側トレースを構成する
このセクションでは、クライアントサイド トレースの構成例を示します。コレクタにエクスポートすることも、オブザーバビリティ バックエンドに直接エクスポートすることもできます。クライアントサイド トレースを構成するには、次のオプションもあります。
- OpenTelemetry API を使用してトレースを構成できます。これには、アプリケーションのコード変更が必要です。次の例をご覧ください。
- 自動エージェントを使用すると、コードを変更せずにトレースを構成できます。環境変数
DATASTORE_ENABLE_TRACING=ONを設定する必要があります。エージェントの構成で説明されているように、他の構成設定も行う必要があります。次の例をご覧ください。
OpenTelemetry API を使用してトレースをコレクタにエクスポートする
次のコードは、サンプリング比率が 10% のスパンを OpenTelemetry Collector にエクスポートするように Datastore 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 use `.setScheduleDelay()`, `.setExporterTimeout()`,
// `.setMaxQueueSize`(), and `.setMaxExportBatchSize()` 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();
DatastoreOptions datastoreOptions = DatastoreOptions
.newBuilder()
.setOpenTelemetryOptions(
DatastoreOpenTelemetryOptions.newBuilder()
.setTracingEnabled(true)
.setOpenTelemetry(otel)
.build())
.build();
Datastore datastore = datastoreOptions.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 use `.setScheduleDelay()`, `.setExporterTimeout()`,
// `.setMaxQueueSize`(), and `.setMaxExportBatchSize()` 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();
DatastoreOptions datastoreOptions = DatastoreOptions
.newBuilder()
.setOpenTelemetryOptions(
DatastoreOpenTelemetryOptions.newBuilder()
.setTracingEnabled(true)
.setOpenTelemetry(otel)
.build())
.build();
Datastore datastore = datastoreOptions.getService();
自動エージェントを使用してコレクタにエクスポートする
OTLP gRPC レシーバーを有効にして OpenTelemetry Collector を実行します。エージェントのエクスポーターを otlp に設定し、エージェントがデータをエクスポートするエンドポイントを指定します。次の例では、サンプリング率を 10% に設定し、localhost ポート 4317 でリッスンする Collector にトレースを送信します。
ターミナル
DATASTORE_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
自動エージェントを使用してオブザーバビリティ バックエンドに直接エクスポートする
環境変数 DATASTORE_ENABLE_TRACING=ON の設定に加えて、特定のバックエンド用の OpenTelemetry Java エージェント拡張機能を追加する必要があります。次の例では、Trace エクスポータ拡張機能と 10% のトレース サンプリング率を使用します。
ターミナル
DATASTORE_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 \
-Dotel.service.name="My Application" \
-jar myapp.jar
トレースの例
次の例は、Cloud Trace でトレース情報がどのように表示されるかを示しています。使用可能な属性と値の詳細については、トレース スパンの属性とイベントをご覧ください。
トレース スパンの例
イベントログの例
属性値の例
次のステップ
- トレーススパンの属性とイベントのリファレンスをご覧ください。
- サーバーサイド モニタリングについて学習します。