クライアントサイドのトレースでパフォーマンスをモニタリングする

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 が有効になっていることを確認します。

クライアント側トレースを構成する

このセクションでは、クライアントサイドトレースの構成例について説明します。Collector にエクスポートすることも、オブザーバビリティバックエンドに直接エクスポートすることもできます。クライアントサイドトレースを構成するには、次のオプションもあります。

トレースは OpenTelemetry API で構成できます。これには、アプリのコード変更が必要です。次の例をご覧ください。
- OpenTelemetry API を使用してコレクタにエクスポートする
- OpenTelemetry API を使用してオブザーバビリティバックエンドに直接エクスポートする
自動エージェントを使用すると、コードを変更せずにトレースを構成できます。環境変数 DATASTORE_ENABLE_TRACING=ON を設定する必要があります。また、エージェントの構成で説明されているように、他の構成設定も設定する必要があります。次の例をご覧ください。
- Auto エージェントを使用してコレクタにエクスポートする
- Auto エージェントを使用してオブザーバビリティバックエンドに直接エクスポートする

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 を使用してオブザーバビリティバックエンドに直接エクスポートする

次のコードは、トレーススパンを Cloud Trace に直接エクスポートし、トレースサンプリング比率を 10% に設定するように 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 でリッスンしているコレクタにトレースを送信します。

ターミナル


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

Auto エージェントを使用してオブザーバビリティバックエンドに直接エクスポートする

環境変数 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 でトレース情報がどのように表示されるかを示しています。使用可能な属性と値の詳細については、トレーススパンの属性とイベントをご覧ください。

トレーススパンの例

Cloud Trace から表示されたトレーススパン。

イベントログの例

Cloud Trace から表示されたトレーススパンのログ。

属性値の例

Cloud Trace から表示されるトレーススパンの属性値。

次のステップ

トレーススパン属性とイベントのリファレンスをご覧ください。
サーバーサイドモニタリングについて学習します。

クライアントサイドのトレースでパフォーマンスをモニタリングする

OpenTelemetry

エクスポータとコレクタを使用してトレースをエクスポートする

制限事項

お支払い

始める前に

クライアント側トレースを構成する

OpenTelemetry API を使用してコレクタにトレースをエクスポートする

Java

OpenTelemetry API を使用してオブザーバビリティ バックエンドに直接エクスポートする

Java

自動エージェントを使用してコレクタにエクスポートする

ターミナル

Auto エージェントを使用してオブザーバビリティ バックエンドに直接エクスポートする

ターミナル

トレースの例

トレーススパンの例

イベントログの例

属性値の例

次のステップ

OpenTelemetry API を使用してオブザーバビリティバックエンドに直接エクスポートする

Auto エージェントを使用してオブザーバビリティバックエンドに直接エクスポートする