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

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 プロトコル（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 を使用してトレースを構成できます。これには、アプリケーションのコードを変更する必要があります。次の例をご覧ください。
- OpenTelemetry 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 でリッスンするコレクタにトレースを送信します。

ターミナル


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

トレーススパンの例

Cloud Trace から見たトレーススパン。

イベントログの例

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

属性値の例

Cloud Trace から見たトレーススパンの属性値。

次のステップ

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

クライアントサイドのトレースでパフォーマンスをモニタリングする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

OpenTelemetry

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

制限事項

お支払い

始める前に

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

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

Java

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

Java

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

ターミナル

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

ターミナル

トレースの例

トレーススパンの例

イベントログの例

属性値の例

次のステップ

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

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

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