Google Cloud は、Java アプリケーションに強力なモニタリング、ロギング、診断機能を提供します。
Java クライアント ライブラリは、トレース、指標、ロギングのデータを出力するように計測されています。インストルメンテーションはオプトインです。明示的に有効にする必要があります。このドキュメントでは、利用可能なシグナルとその有効化方法について説明します。
利用可能なシグナル
ゴールデン シグナルには、OpenTelemetry セマンティック規則に準拠した次のテレメトリー データが含まれます。
- トレース: クライアント ライブラリによって行われたネットワーク リクエストを表す低レベルの HTTP/gRPC トレース。
- 指標: レイテンシとリクエスト率を追跡するクライアント リクエスト指標。プライマリ指標は
gcp.client.request.durationです。 - ログ:
DEBUGレベルで実行可能なエラーログ。最終的にリトライが成功した場合でも、トランスポート レイヤで失敗したリクエストの詳細を提供します。
シグナルには、標準の OpenTelemetry 属性（http.response.status_code や rpc.system.name など）と Google Cloud固有のカスタム属性が含まれます。カスタム属性には、次のような属性が含まれる場合があります。
gcp.client.service: サービス名（pubsub、storageなど）。gcp.client.repo: クライアント ライブラリ リポジトリ（例:googleapis/google-cloud-java）。gcp.client.version: クライアント ライブラリのバージョン。gcp.client.artifact: 特定のモジュール パス（例:com.google.cloud:google-cloud-secretmanager）。gcp.resource.destination.id: 処理対象のリソースの ID。gcp.errors.domain: アクション可能なエラーログのエラー ドメイン。gcp.errors.metadata.<key>: 失敗したリクエストの追加のエラー メタデータキー（フラット化）。
標準の属性の一覧については、OpenTelemetry HTTP と gRPC のセマンティック規約をご覧ください。
テレメトリーを有効にする
センシティブ データを保護するため、テレメトリー シグナルはデフォルトで無効になっています。有効にするには、明示的にオプトインする必要があります。
トレースと指標
生成された Java クライアント ライブラリでは、初期化中に適切なトレーサー Factory をクライアントの設定に指定することで、プログラマティックにトレースと指標を有効にする必要があります。
- トレース:
OpenTelemetryTracingFactoryを使用してクライアントを構成します。 - 指標:
OpenTelemetryMetricsFactoryを使用してクライアントを構成します。 - 両方: トレースと指標の両方を有効にする場合は、両方のファクトリをラップする
CompositeTracerFactoryを使用してクライアントを構成します。
ロギング
実行可能なエラーログは、コアの ApiTracer フレームワークに直接統合されます。 Google Cloudクライアント ライブラリ全体でアクション可能なエラーログをグローバルに有効にするには、次の環境変数を使用します。
export GOOGLE_SDK_JAVA_LOGGING=true
トレース コンテキストの伝播
Java クライアント ライブラリでのトレース コンテキストの伝播では、トレースを明示的に有効にする必要があります。
トレース生成が有効になっていて（たとえば、OpenTelemetryTracingFactory を構成して）、クライアント ライブラリ メソッドが呼び出されたときにアプリケーションの現在のコンテキストにアクティブな OpenTelemetry スパンがある場合、ライブラリはそれを使用して送信リクエストのトレース コンテキストを提供します。これにより、アプリケーション レベルのトレースをバックエンド サービスのログと動作に関連付けることができます。
テレメトリーのエクスポート
クライアント ライブラリでテレメトリーを有効にしたら、このデータを収集してオブザーバビリティ バックエンドにエクスポートするようにアプリケーションを構成する必要があります。
トレースと指標
Java クライアント ライブラリで生成されたトレースと指標をエクスポートするには、目的のエクスポータ（OTLP など）で OpenTelemetry SDK を初期化し、アプリケーションでグローバル テキストマップ プロパゲータを設定します。
OpenTelemetry データを収集して Cloud Monitoring または Cloud Trace にエクスポートする方法の詳細については、インストルメンテーション アプローチを選択するをご覧ください。
ロギング
Java クライアント ライブラリは、SLF4J や java.util.logging などの標準的なロギング フレームワークを使用します。GOOGLE_SDK_JAVA_LOGGING=true が設定されている場合、操作可能なエラーログが DEBUG レベルで出力されます。
これらの構造化ログを Cloud Logging に転送するには、JSON を標準出力（stdout）に書き込むようにロギング フレームワーク（Logback など）を構成します。Google Kubernetes Engine や Cloud Run などの環境にデプロイする場合は、組み込みのエージェントがこれらのログを自動的にスクレイピングします。
トレース相関関係など、Cloud Logging 互換の JSON を出力するように Logback または java.util.logging を構成する手順の詳細については、Java の構造化ロギングを構成するをご覧ください。