Java 用 Cloud Trace の設定

Java アプリケーション用の Cloud Trace を有効にするには、OpenCensus を使用します。OpenCensus は、複数のバックエンドで機能するトレースと指標データを収集するための、一連のインストゥルメンテーション ライブラリです。Java 用の OpenCensus に関する最新情報、その他のドキュメントとサンプルについては、census-instrumentation/opencensus-java をご覧ください。

ライブラリのインストール

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

Maven

<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-api</artifactId>
  <version>0.27.1</version>
</dependency>
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-exporter-trace-stackdriver</artifactId>
  <version>0.27.1</version>
</dependency>
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-impl</artifactId>
  <version>0.27.1</version>
  <scope>runtime</scope>
</dependency>
<dependency>
   <groupId>joda-time</groupId>
   <artifactId>joda-time</artifactId>
   <version>2.10.6</version>
</dependency>

Gradle

compile 'io.opencensus:opencensus-api:0.26.0'
compile 'io.opencensus:opencensus-exporter-trace-stackdriver:0.26.0'
runtime 'io.opencensus:opencensus-impl:0.26.0'

Stackdriver エクスポータの構成

収集したトレースデータをエクスポートするには、StackdriverTraceExporter オブジェクトを使用します。

public static void createAndRegisterGoogleCloudPlatform(String projectId) throws IOException {
  StackdriverTraceExporter.createAndRegister(
      StackdriverTraceConfiguration.builder().setProjectId(projectId).build());
}

Google Cloud インフラストラクチャ上で実行している場合、setProjectID を呼び出して Google Cloud プロジェクト ID を指定する必要はありません。このフィールドを設定しない場合、Java 用クライアント ライブラリは Google Cloud メタデータ サーバーからこのデータを自動的に収集します。

Google Cloud インフラストラクチャ上で実行していない場合は、Google Cloud プロジェクト ID をアプリケーションに指定する必要があります。

Google Cloud プロジェクト ID を明示的に設定しない場合、google-cloud Java ライブラリは環境変数 GOOGLE_CLOUD_PROJECT が設定されているかどうかを自動的に判断します。この変数が設定されている場合、ライブラリは Google Cloud プロジェクト ID として GOOGLE_CLOUD_PROJECT の値を使用します。

詳細については、google-cloud-library によるプロジェクト ID の指定をご覧ください。 環境変数を設定するには、次の操作を行います。

Linux または macOS

export GOOGLE_CLOUD_PROJECT=your-project-id

Windows

set GOOGLE_CLOUD_PROJECT=your-project-id

PowerShell:

$env:GOOGLE_CLOUD_PROJECT="your-project-id"

カスタム トレーススパンの追加

OpenCensus ライブラリには、一般的なウェブ フレームワークと RPC フレームワークの自動統合がいくつか含まれていますが、カスタム トレースを作成することもできます。

private static final Tracer tracer = Tracing.getTracer();

public static void doWork() {
  // Create a child Span of the current Span.
  try (Scope ss = tracer.spanBuilder("MyChildWorkSpan").startScopedSpan()) {
    doInitialWork();
    tracer.getCurrentSpan().addAnnotation("Finished initial work");
    doFinalWork();
  }
}

private static void doInitialWork() {
  // ...
  tracer.getCurrentSpan().addAnnotation("Doing initial work");
  // ...
}

private static void doFinalWork() {
  // ...
  tracer.getCurrentSpan().addAnnotation("Hello world!");
  // ...
}

Cloud Logging との統合の構成

Cloud Trace データを Cloud Logging に送信する方法については、Cloud Logging との統合をご覧ください。

フル サンプリングの有効化

デフォルトでは、10,000 個のトレースのうち、サンプリングされるトレースは 1 個だけです。

開発環境では、このサンプリング レートは遅すぎて十分なトレースデータが示されない場合があります。すべてのトレースをサンプリングするには、alwaysSample オプションを使用します。

フル サンプリングを有効にするには、setSampler メソッドを使用して alwaysSample オプションを指定します。

public static void doWorkFullSampled() {
  try (Scope ss =
      tracer
          .spanBuilder("MyChildWorkSpan")
          .setSampler(Samplers.alwaysSample())
          .startScopedSpan()) {
    doInitialWork();
    tracer.getCurrentSpan().addAnnotation("Finished initial work");
    doFinalWork();
  }
}

自動認証のオーバーライド

自動認証とプロジェクト選択はオーバーライドできます。たとえば、次の例では、認証情報の作成から 60 秒後に期限切れになるエクスポータを作成しています。

public static void createAndRegisterWithToken(String accessToken) throws IOException {
  Date expirationTime = DateTime.now().plusSeconds(60).toDate();

  GoogleCredentials credentials =
      GoogleCredentials.create(new AccessToken(accessToken, expirationTime));
  StackdriverTraceExporter.createAndRegister(
      StackdriverTraceConfiguration.builder()
          .setProjectId("MyStackdriverProjectId")
          .setCredentials(credentials)
          .build());
}

プラットフォームの構成

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

Google Cloud での実行

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

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

  • App Engine フレキシブル環境
  • App Engine スタンダード環境

  • Google Kubernetes Engine(GKE)

  • Compute Engine

カスタム アクセス スコープを使用する場合は、Cloud Trace API のアクセス スコープを有効にする必要があります。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)を使用してアプリケーションの認証情報を検索します。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"

トレースの表示

デプロイ後は、Cloud Console Trace Viewer でトレースを表示できます。

Trace Viewer のページに移動

トラブルシューティング

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

リソース