Spring Cloud Sleuth と Cloud Trace を使用した分散トレース

1. 概要

分散トレースは、多層マイクロサービスアーキテクチャの分析情報とオブザーバビリティを取得するために重要です。サービス A からサービス B、サービス C へとサービス間の呼び出しが連鎖している場合、呼び出しが成功したかどうかと、各ステップのレイテンシを把握することが重要です。

Spring Boot では、Spring Cloud Sleuth を使用して、分散トレース計測をアプリケーションにシームレスに追加できます。デフォルトでは、トレースデータを Zipkin に転送できます。

Google Cloud Platform には Cloud Trace があります。これは、独自の Zipkin インスタンスやストレージを管理することなく、トレースデータを保存できるマネージドサービスです。Cloud Trace では、レイテンシ分布レポートを生成し、パフォーマンスの回帰を自動的に検出することもできます。

Spring Boot アプリケーションから Cloud Trace を使用するには、次の 2 つの方法があります。

Stackdriver Trace Zipkin Proxy を使用し、このプロキシを Zipkin エンドポイントとして使用するように Spring Cloud Sleuth を構成します。
または、Spring Cloud Sleuth とシームレスに統合され、トレースデータを Cloud Trace に直接転送する Spring Cloud GCP Trace を使用します。

この Codelab では、新しい Spring Boot アプリケーションを構築し、分散トレースに Spring Cloud GCP Trace を使用する方法を学びます。

学習内容

Spring Boot Java アプリケーションを作成して Cloud Trace を構成する方法。

必要なもの

Google Cloud Platform プロジェクト
Chrome や Firefox などのブラウザ
Linux の標準的なテキストエディタ（vim、emacs、nano など）を使い慣れていること

このチュートリアルをどのように使用されますか？

通読するのみ

通読し、演習を行う

HTML/CSS ウェブアプリの作成経験についてお答えください。

初心者

中級者

上級者

Google Cloud Platform サービスのご利用経験についてどのように評価されますか？

初心者

中級者

上級者

2. 設定と要件

セルフペース型の環境設定

Google Cloud Console にログインして、プロジェクトを新規作成するか、既存のプロジェクトを再利用します。Gmail アカウントも Google Workspace アカウントもまだお持ちでない場合は、アカウントを作成してください。

プロジェクト名は、このプロジェクトの参加者に表示される名称です。Google API では使用されない文字列です。いつでも更新できます。
プロジェクト ID は、すべての Google Cloud プロジェクトにおいて一意でなければならず、不変です（設定後は変更できません）。Cloud コンソールでは一意の文字列が自動生成されます。通常は、この内容を意識する必要はありません。ほとんどの Codelab では、プロジェクト ID（通常は PROJECT_ID と識別されます）を参照する必要があります。生成された ID が好みではない場合は、ランダムに別の ID を生成できます。または、ご自身で試して、利用可能かどうかを確認することもできます。このステップ以降は変更できず、プロジェクトを通して同じ ID になります。
なお、3 つ目の値として、一部の API が使用するプロジェクト番号があります。これら 3 つの値について詳しくは、こちらのドキュメントをご覧ください。

次に、Cloud のリソースや API を使用するために、Cloud コンソールで課金を有効にする必要があります。この Codelab の操作をすべて行って、費用が生じたとしても、少額です。このチュートリアルの終了後に請求が発生しないようにリソースをシャットダウンするには、作成したリソースを削除するか、プロジェクトを削除します。Google Cloud の新規ユーザーは、300 米ドル分の無料トライアルプログラムをご利用いただけます。

Google Cloud Shell

Google Cloud と Kubernetes はノートパソコンからリモートで操作できますが、この Codelab では、Google Cloud Shell（Cloud 上で動作するコマンドライン環境）を使用します。

Cloud Shell をアクティブにする

Cloud Console で、[Cloud Shell をアクティブにする] をクリックします。

Cloud Shell を初めて起動する場合は、その内容を説明する中間画面が表示されます。中間画面が表示された場合は、[続行] をクリックします。

すぐにプロビジョニングが実行され、Cloud Shell に接続されます。

この仮想マシンには、必要な開発ツールがすべて用意されています。仮想マシンは Google Cloud で稼働し、永続的なホームディレクトリが 5 GB 用意されているため、ネットワークのパフォーマンスと認証が大幅に向上しています。このコードラボで行う作業のほとんどはブラウザから実行できます。

Cloud Shell に接続すると、認証が完了しており、プロジェクトに各自のプロジェクト ID が設定されていることがわかります。

Cloud Shell で次のコマンドを実行して、認証されたことを確認します。

gcloud auth list

コマンド出力

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Cloud Shell で次のコマンドを実行して、gcloud コマンドがプロジェクトを認識していることを確認します。

gcloud config list project

コマンド出力

[core]
project = <PROJECT_ID>

上記のようになっていない場合は、次のコマンドで設定できます。

gcloud config set project <PROJECT_ID>

コマンド出力

Updated property [core/project].

3. 新しい Spring Boot REST サービスを作成する

Cloud Shell の起動後に以下のコマンドラインを使用すると、Spring Initializr を使用して新しい Spring Boot アプリケーションを生成できます。

$ curl https://start.spring.io/starter.tgz -d packaging=jar \
  -d bootVersion=2.7.6 \
  -d dependencies=web,lombok,cloud-gcp,distributed-tracing \
  -d jvmVersion=17 \
  -d type=maven-project \
  -d baseDir=trace-service-one | tar -xzvf - \
  && cd trace-service-one

新しいクラスを追加して、新しい REST コントローラを作成します。

src/main/java/com/example/demo/WorkController.java

package com.example.demo;

import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.Random;

@RestController
@Slf4j
public class WorkController {
  Random r = new Random();

  public void meeting() {
    try {
      log.info("meeting...");
      // Delay for random number of milliseconds.
      Thread.sleep(r.nextInt(500));
    } catch (InterruptedException e) {
    }
  }

  @GetMapping("/")
  public String work() {
    // What is work? Meetings!
    // When you hit this URL, it'll call meetings() 5 times.
    // Each time will have a random delay.
    log.info("starting to work");
    for (int i = 0; i < 5; i++) {
      this.meeting();
    }
    log.info("finished!");
    return "finished work!";
  }
}

アプリケーションに適した JVM バージョンがあることを確認します。

$ export JAVA_HOME=/usr/lib/jvm/java-1.17.0-openjdk-amd64

Spring Boot プラグインを使用して、Spring Boot アプリケーションを通常どおり起動できます。このラボのテストをスキップしましょう。

$ ./mvnw -DskipTests spring-boot:run

アプリケーションが開始したら、Cloud Shell ツールバーのウェブでプレビューアイコンをクリックし、[プレビューのポート: 8080] を選択します。

しばらくすると、次のような結果が表示されます。

Cloud Shell に、トレース ID とスパン ID を含むログメッセージも表示されます。

4. Cloud Trace の使用

Cloud Trace API を有効にする

Cloud Trace を使用してトレースデータを保存する前に、Cloud Trace API を有効にする必要があります。API を有効にするには、次のコマンドを実行します。

$ gcloud services enable cloudtrace.googleapis.com

アプリケーションのデフォルト認証情報を設定する

このラボでは、アプリケーションのデフォルト認証情報を構成する必要があります。この認証情報は、Spring Cloud GCP Trace スターターによって自動的に取得されます。

まず、ログインします。

$ gcloud auth application-default login
You are running on a Google Compute Engine virtual machine.
The service credentials associated with this virtual machine
will automatically be used by Application Default
Credentials, so it is not necessary to use this command.
If you decide to proceed anyway, your user credentials may be visible
to others with access to this virtual machine. Are you sure you want
to authenticate with your personal account?
Do you want to continue (Y/n)? Y

Go to the following link in your browser:
    https://accounts.google.com/o/oauth2/auth...
Enter verification code: ...

リンクをクリックして新しいブラウザタブを開き、[許可] をクリックします。

次に、確認コードをコピーして Cloud Shell に貼り付け、Enter キーを押します。以下のように表示されます。

Credentials saved to file: [/tmp/tmp.jm9bnQ4R9Q/application_default_credentials.json]
These credentials will be used by any library that requests
Application Default Credentials.

Spring Cloud GCP Trace を追加する

このサービスでは、トレースに Spring Cloud Sleuth をすでに使用しています。Spring Cloud GCP Trace スターターを追加して、データを Cloud Trace に転送しましょう。

Spring Cloud GCP Trace の依存関係を追加します。

pom.xml

<project>
  ...
  <dependencies>
    ...
    <!-- Add Cloud Trace Starter -->
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>spring-cloud-gcp-starter-trace</artifactId>
    </dependency>
  </dependencies>
  ...
</project>

デフォルトでは、Spring Cloud Sleuth はすべてのリクエストをサンプリングしません。テストを少し簡単にするために、application.properties でサンプルレートを 100% に増やして、トレースデータを確認できるようにします。また、重要でない URL を無視します。

$ echo "
spring.sleuth.sampler.probability=1.0
spring.sleuth.web.skipPattern=(^cleanup.*|.+favicon.*)
" > src/main/resources/application.properties

アプリケーションを再度実行し、Cloud Shell のウェブプレビューを使用してアプリケーションを表示します。

$ export GOOGLE_CLOUD_PROJECT=`gcloud config list --format 'value(core.project)'`
$ ./mvnw -DskipTests spring-boot:run

デフォルトでは、Spring Cloud GCP Trace はトレースデータをバッチ処理し、10 秒ごと、または最小数のトレースデータを受信したときに送信します。これは構成可能であり、詳細については Spring Cloud GCP Trace リファレンスドキュメントをご覧ください。

サービスにリクエストを送信します。

$ curl localhost:8080

Cloud Console で、[オペレーション] → [トレース] → [トレースリスト] に移動します。

上部で、期間を 1 時間に絞り込みます。デフォルトでは、[自動再読み込み] はオンになっています。トレースデータが到着すると、コンソールに表示されます。

トレースデータは 30 秒ほどで表示されます。

青い点をクリックすると、トレースの詳細が表示されます。

とても簡単でした。

5. 2 つ目の Spring Boot ウェブアプリケーションを作成する

+ アイコンをクリックして、新しい Cloud Shell セッションを開きます。

新しいセッションで、2 つ目の Spring Boot アプリケーションを作成します。

$ curl https://start.spring.io/starter.tgz -d packaging=jar \
  -d bootVersion=2.7.6 \
  -d dependencies=web,lombok,cloud-gcp,distributed-tracing \
  -d jvmVersion=17 \
  -d type=maven-project \
  -d baseDir=trace-service-two | tar -xzvf - \
  && cd trace-service-two

新しいクラスを追加して、新しい REST コントローラを作成します。

src/main/java/com/example/demo/MeetingController.java

package com.example.demo;

import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.Random;

@RestController
@Slf4j
public class MeetingController {
  Random r = new Random();

  @GetMapping("/meet")
  public String meeting() {
    try {
      log.info("meeting...");
      Thread.sleep(r.nextInt(500 - 20 + 1) + 20);
    } catch (InterruptedException e) {
    }
    return "finished meeting";
  }
}

pom.xml に Spring Cloud GCP Trace を追加する

pom.xml

<project>
  ...
  <dependencies>
    ...
    <!-- Add Cloud Trace starter -->
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>spring-cloud-gcp-starter-trace</artifactId>
    </dependency>
  </dependencies>
  ...
</project>

リクエストの 100% をサンプリングするように Sleuth を構成します。

src/main/resources/application.properties

$ echo "
spring.sleuth.sampler.probability=1.0
spring.sleuth.web.skipPattern=(^cleanup.*|.+favicon.*)
" > src/main/resources/application.properties

最後に、Spring Boot プラグインを使用して、ポート 8081 で Spring Boot アプリケーションを起動できます。

$ export GOOGLE_CLOUD_PROJECT=`gcloud config list --format 'value(core.project)'`
$ ./mvnw -DskipTests spring-boot:run -Dspring-boot.run.jvmArguments="-Dserver.port=8081"

6. セカンドサービスを使用するようにファーストサービスを更新する

trace-service-two が実行されている間に、最初の Cloud Shell セッションウィンドウに戻り、trace-service-one を変更します。

まず、新しい RestTemplate Bean を初期化します。

src/main/java/com/example/demo/DemoApplication.java

package com.example.demo;

...

import org.springframework.web.client.RestTemplate;
import org.springframework.context.annotation.Bean;

@SpringBootApplication
public class DemoApplication {
        @Bean
        public RestTemplate restTemplate() {
                return new RestTemplate();
        }
        
        public static void main(String[] args) {
                SpringApplication.run(DemoApplication.class, args);
        }
}

WorkController.meeting() で、Meeting サービスを呼び出します。

src/main/java/com/example/demo/WorkController.java

package com.example.demo;

...
import org.springframework.web.client.RestTemplate;
import org.springframework.beans.factory.annotation.Autowired;

@RestController
@Slf4j
public class WorkController {
  @Autowired
  RestTemplate restTemplate;

  public void meeting() {
    String result = restTemplate.getForObject("http://localhost:8081/meet", String.class);
    log.info(result);
  }

  ...
}

サービスを再度起動し、コマンドラインからエンドポイントをトリガーします。

$ export GOOGLE_CLOUD_PROJECT=`gcloud config list --format 'value(core.project)'`

# The '&' places the process in the background. Bring it back to the foreground with 'fg'.
$ ./mvnw -DskipTests spring-boot:run &

$ curl localhost:8080

両方のセッションウィンドウに、ログメッセージが表示されます。Trace ID は、あるサービスから別のサービスに伝播されます。

Cloud Trace のトレースリストに、2 番目のトレースが表示されます。

新しい青い点をクリックすると、トレースの詳細が表示されます。

この図の任意のスパンをクリックして、スパンの詳細を表示することもできます。

7. レイテンシ分布とパフォーマンスレポート

Cloud Trace をトレースデータのストレージとして使用すると、Cloud Trace はデータを使用してレイテンシ分布レポートを作成できます。このようなレポートを作成するには、100 件を超えるトレースが必要です。

最初の 100 件以上のリクエストは、Cloud Shell にプリインストールされている hey を使用して実行できます。

$ hey localhost:8080 -n 150

また、Cloud Trace は、[分析レポート] で、2 つの異なる期間にわたる同じサービスのパフォーマンスの回帰を自動的に検出できます。

8. まとめ

このラボでは、2 つのシンプルなサービスを作成し、Spring Cloud Sleuth を使用して分散トレースを追加し、Spring Cloud GCP を使用してトレース情報を Cloud Trace に転送しました。

9. 完了

初めての App Engine ウェブアプリケーションを作成する方法を学習しました。

詳細

Cloud Trace: https://cloud.google.com/trace/
GCP プロジェクトの Spring: http://cloud.spring.io/spring-cloud-gcp/
Spring on GCP GitHub リポジトリ: https://github.com/GoogleCloudPlatform/spring-cloud-gcp
Google Cloud Platform での Java: https://cloud.google.com/java/

ライセンス

この作業はクリエイティブ・コモンズの表示 2.0 汎用ライセンスにより使用許諾されています。

Spring Cloud Sleuth と Cloud Trace を使用した分散トレース

1. 概要

学習内容

必要なもの

このチュートリアルをどのように使用されますか？

HTML/CSS ウェブアプリの作成経験についてお答えください。

Google Cloud Platform サービスのご利用経験についてどのように評価されますか？

2. 設定と要件

セルフペース型の環境設定

Google Cloud Shell

Cloud Shell をアクティブにする

3. 新しい Spring Boot REST サービスを作成する

4. Cloud Trace の使用

Cloud Trace API を有効にする

アプリケーションのデフォルト認証情報を設定する

Spring Cloud GCP Trace を追加する

5. 2 つ目の Spring Boot ウェブ アプリケーションを作成する

6. セカンド サービスを使用するようにファースト サービスを更新する

7. レイテンシ分布とパフォーマンス レポート

8. まとめ

9. 完了

詳細

ライセンス

5. 2 つ目の Spring Boot ウェブアプリケーションを作成する

6. セカンドサービスを使用するようにファーストサービスを更新する

7. レイテンシ分布とパフォーマンスレポート