Java 用の Stackdriver Trace の設定

Trace の Java サポートは、複数のバックエンドで動作するトレースおよびアプリケーションの指標のインストゥルメンテーション ライブラリ セットである OpenCensus によって提供されます。Java 用の OpenCensus に関する最新情報、追加のドキュメントとサンプルについては、GitHub ページをご覧ください。

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

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

Maven

<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-api</artifactId>
  <version>0.12.2</version>
</dependency>
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-exporter-trace-stackdriver</artifactId>
  <version>0.12.2</version>
</dependency>
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-impl</artifactId>
  <version>0.12.2</version>
  <scope>runtime</scope>
</dependency>

Gradle

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

Stackdriver エクスポータの構成

収集したデータをエクスポートするには、Stackdriver エクスポータを使用します。Stackdriver エクスポータでは、認証にアプリケーションのデフォルト認証情報を使用します。コードが Google Cloud Platform(GCP)で実行されている場合は、プロジェクト ID を省略できます。

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

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

Java 用の Stackdriver Trace ライブラリには複数の一般的なウェブおよび 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!");
  // ...
}

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

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

開発環境では、このサンプリング レートは小さすぎて十分なトレースデータが示されない場合があります。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();
  }
}

Google Cloud Platform での実行

Google Cloud Platform 上で実行されているインスタンスで Stackdriver Trace API アクセス スコープが有効になっている場合は、そのインスタンス用の認証情報を提供する必要はありません。ただし、インスタンスに対して可能な限り広いアクセス スコープを設定してから、Cloud Identity and Access Management を使用して、アクセスを制限することをおすすめします。

自動的な認証とプロジェクト選択をオーバーライドするには、次のコードを使用します。

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());
}

App Engine フレキシブル環境

App Engine フレキシブル環境では Stackdriver Trace API アクセス スコープがデフォルトで有効であり、認証情報やプロジェクト ID を提供しなくても OpenCensus クライアント ライブラリを使用できます。

App Engine スタンダード環境

App Engine スタンダード環境では Stackdriver Trace API アクセス スコープがデフォルトで有効であり、認証情報やプロジェクト ID を提供しなくても OpenCensus クライアント ライブラリを使用できます。

GKE

GKE で、クラスタの作成時に trace.append OAuth アクセス スコープを追加します。

gcloud container clusters create example-cluster-name --scopes https://www.googleapis.com/auth/trace.append

クラスタの作成後に、そのアクセス スコープを変更することはできません。

Compute Engine

Compute Engine VM インスタンスの場合は、各 VM インスタンスに Stackdriver Trace API アクセス スコープ trace.append を明示的に有効にする必要があります。Google Cloud Platform Console から新しいインスタンスを作成する場合は、[インスタンスの作成] パネルの [ID と API へのアクセス] セクションで次の値を選択します。

  1. [サービス アカウント] には [Compute Engine のデフォルトのサービス アカウント] を選択します
  2. [アクセス スコープ] には [すべての Cloud API に完全アクセス権を許可] を選択します

Compute Engine のデフォルト以外のサービス アカウントを使用するには、インスタンスのサービス アカウントの作成と有効化と、ローカルやその他の場所での実行をご覧ください。重要なのは、使用するサービス アカウントに Cloud Trace Agent の役割があることです。

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

Stackdriver Trace を GCP 以外で実行するには、GCP プロジェクト ID と該当するサービス アカウントの認証情報を OpenCensus クライアント ライブラリに直接提供する必要があります。詳細については、アプリケーションの認証情報を指定するをご覧ください。

プロジェクト ID

Stackdriver エクスポータの構成の説明に沿って、プロジェクト ID を OpenCensus に提供します。環境変数 GOOGLE_CLOUD_PROJECT をプロジェクト ID に設定し、この変数を読み取るようにアプリケーションを変更することをおすすめします。Java の場合、後者のステップは必須ではありません。この環境変数が利用可能な場合、OpenCensus から呼び出される google-cloud-java ライブラリがこの変数を読み取り、使用します。詳しくは、プロジェクト ID を指定する google-cloud-library をご覧ください。

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"

認証情報

GCP クライアント ライブラリでは、アプリケーションのデフォルト認証情報(ADC)を使用してアプリケーションの認証情報を検出します。OpenCensus クライアント ライブラリに認証情報を提供するには、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"

トレースの表示

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

Trace Viewer のページに移動

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。