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

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 を使用してコレクタにトレースをエクスポートする

次のコードは、サンプリング率が 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 から表示されるトレーススパンの属性値。

次のステップ