Java と OpenTelemetry

このページは、OpenTelemetry を使用して Java アプリケーション用の Cloud Trace データを収集するアプリケーション開発者を対象としています。OpenTelemetry は、トレースデータと指標データを収集するために使用できる、ベンダーに依存しないインストルメンテーションフレームワークです。コードのインストルメンテーションの詳細については、インストルメンテーションとオブザーバビリティをご覧ください。

OpenTelemetry パッケージをインストールする。
Cloud Trace にスパンをエクスポートするようにアプリケーションを構成する。
プラットフォームを構成する。

リリース情報については、以下をご覧ください。

OpenTelemetry リファレンスコンテンツについては、以下をご覧ください。

追加のドキュメントとサンプルを含め、Java の OpenTelemetry に関する最新情報については、OpenTelemetry をご覧ください。

始める前に

Java 8 以降を使用する必要があります。
Google Cloud コンソールのナビゲーションパネルで [API とサービス] を選択し、[API とサービスを有効化] をクリックして、Cloud Trace API を有効にします。
[Cloud Trace API の設定] に移動
[API が有効です] が表示されている場合、API はすでに有効になっています。そうでない場合は、[有効にする] ボタンをクリックします。

OpenTelemetry パッケージをインストールする

トレースを収集するには、アプリケーションの Maven または Gradle ファイルに OpenTelemetry トレースと OpenTelemetry 用 Cloud Trace エクスポータを追加します。

OpenTelemetry の依存関係の最新リストについては、Maven と Gradle をご覧ください。
必要なエクスポータの依存関係については、次の表をご覧ください。
Maven
```
<dependency>
  <groupId>com.google.cloud.opentelemetry</groupId>
  <artifactId>exporter-trace</artifactId>
  <version>0.15.0</version>
</dependency>
```
上記のステートメントは、エクスポータのバージョンを指定しています。最新のエクスポータリリースを選択してください。
Gradle
```
implementation 'com.google.cloud.opentelemetry:exporter-trace:0.15.0'
```
前のステートメントは、エクスポータのバージョンを指定しています。最新のエクスポータリリースを選択してください。

Cloud Trace へのスパンのエクスポートを構成する

収集したトレースデータをエクスポートするには、TraceExporter オブジェクトを使用します。デフォルトの構成でこのオブジェクトを作成する方法を示します。

TraceExporter traceExporter = TraceExporter.createWithDefaultConfiguration();

構成を指定して、それをエクスポータに渡すこともできます。たとえば、次のコードは Google Cloud プロジェクトを設定します。

TraceExporter traceExporter = TraceExporter.createWithConfiguration(
  TraceConfiguration.builder().setProjectId("MY_PROJECT").build());

エクスポータを構成したら、TracerProvider を設定します。

OpenTelemetrySdk.builder()
          .setTracerProvider(
              SdkTracerProvider.builder()
                  .addSpanProcessor(BatchSpanProcessor.builder(traceExporter).build())
                  .build())
          .buildAndRegisterGlobal();

前の例では、BatchSpanProcessor の呼び出しにより、プロバイダがバックグラウンドプロセスでスパンを送信するように構成します。

認証フィールドの設定方法については、OpenTelemetry 用 Cloud Trace エクスポータの設定セクションをご覧ください。

スパンの作成

トレーススパンをキャプチャするようにアプリケーションを構成する方法については、OpenTelemetry トレースをご覧ください。このページでは、次のすべてを行う方法について説明します。

スパンを作成する
ネストされたスパンを作成する
スパン属性を設定する
イベントを使用してスパンを作成する
リンクを使用してスパンを作成する

サンプリングを構成する

トレースをサンプリングするタイミングの構成方法については、OpenTelemetry サンプラーをご覧ください。このページでは、利用可能なサンプリングオプションについて説明します。

サンプルアプリケーション

サンプルアプリケーションについては、TraceExporterExample.java をご覧ください。

プラットフォームの構成

Cloud Trace は Google Cloud と他のプラットフォームで使用できます。

Google Cloud での実行

アプリケーションが Google Cloud で実行されている場合、認証情報をサービスアカウントの形式でクライアントライブラリに提供する必要はありません。ただし、Google Cloud Platform で Cloud Trace API のアクセススコープが有効になっている必要があります。

サポートされている Google Cloud 環境の一覧については、環境サポートをご覧ください。

次の構成では、デフォルトのアクセススコープ設定により Cloud Trace API が有効化されます。

App Engine フレキシブル環境
App Engine スタンダード環境
Google Kubernetes Engine（GKE）

注: Autopilot を使用している場合、または GKE クラスタで Workload Identity を有効にする場合は、Workload Identity を使用するようにアプリケーションを構成します。
Compute Engine
Cloud Run

カスタムアクセススコープを使用する場合は、Cloud Trace API のアクセススコープを有効にする必要があります。

Google Cloud Console を使用して環境のアクセススコープを構成する方法については、Google Cloud プロジェクトの構成をご覧ください。
gcloud ユーザーの場合は、--scopes フラグを使用してアクセススコープを指定し、trace.append Cloud Trace API アクセススコープを含めます。たとえば、Cloud Trace API のみを有効にして GKE クラスタを作成するには、次のようにします。
```
gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append
```

ローカルやその他の場所での実行

アプリケーションが Google Cloud の外部で実行されている場合は、認証情報をサービスアカウントの形式でクライアントライブラリに提供する必要があります。サービスアカウントには Cloud Trace エージェントロールが含まれている必要があります。手順については、サービスアカウントの作成をご覧ください。

Google Cloud クライアントライブラリは、アプリケーションのデフォルト認証情報（ADC）を使用してアプリケーションの認証情報を検索します。

これらの認証情報を指定するには、次の 3 つの方法があります。

実行 gcloud auth application-default login
オペレーティングシステムのデフォルトパスにサービスアカウントを配置します。以下に、Windows と Linux のデフォルトのパスを一覧表示します。
- Windows: %APPDATA%/gcloud/application_default_credentials.json
- Linux: $HOME/.config/gcloud/application_default_credentials.json
GOOGLE_APPLICATION_CREDENTIALS 環境変数をサービスアカウントのパスに設定します。

Linux / macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

トレースを表示

Google Cloud コンソールのナビゲーションパネルで [Trace] を選択し、次に [ Trace エクスプローラ] を選択します。

[Trace エクスプローラ] に移動

トラブルシューティング

Cloud Trace に関する問題のトラブルシューティングについては、トラブルシューティングページをご覧ください。

リソース

https://opentelemetry.io/
OpenTelemetry/opentelemetry-java GitHub リポジトリ
Google Cloud opentelemetry-operations-java GitHub リポジトリ