Spring Cloud Sleuth や Spring 全般を始めようとしている場合は、まずこのセクションを読むことから始めましょう。基本的な「何?」、「どのように?」、「なぜ?」の質問に回答します。Spring Cloud Sleuth の導入とインストール手順も含まれています。次に、最初の Spring Cloud Sleuth アプリケーションを構築する方法を説明し、いくつかの基本原則を説明しながら進めていきます。

1. Spring Cloud Sleuth の導入

Spring Cloud Sleuth は、Spring Cloud (英語) の分散トレースソリューション用の API を提供します。OpenZipkin Brave [GitHub] (英語) と統合します

Spring Cloud Sleuth は、リクエストとメッセージを追跡できるため、その通信を対応するログエントリに関連付けることができます。トレース情報を外部システムにエクスポートして、待ち時間を視覚化することもできます。Spring Cloud Sleuth は、OpenZipkin (英語) 互換システムを直接サポートします。

1.1. 用語

Spring Cloud Sleuth は Dapper (英語) の用語を借用しています。

スパン : 作業の基本単位。例: RPC へのレスポンスの送信と同様に、RPC の送信は新しいスパンです。スパンには、説明、タイムスタンプ付きイベント、Key-Value アノテーション(タグ)、引き起こしたスパンの ID、プロセス ID(通常は IP アドレス)などの他のデータもあります。

スパンは開始および停止でき、タイミング情報を追跡します。スパンを作成したら、将来のある時点で停止する必要があります。

トレース : 木のような構造を形成するスパンのセット。例: 分散ビッグデータストアを実行している場合、PUT リクエストによってトレースが形成される可能性があります。

アノテーション / イベント : イベントの存在を時間内に記録するために使用されます。

概念的には、典型的な RPC シナリオでは、これらのイベントにマークを付けて、発生したアクションの種類を強調表示します(物理的にそのようなイベントがスパンに設定されることを意味するわけではありません)。

  • cs: クライアントが送信しました。クライアントがリクエストを行いました。このアノテーションは、スパンの開始を示します。

  • sr: 受信したサーバー: サーバー側がリクエストを受け取り、処理を開始しました。このタイムスタンプから cs タイムスタンプを差し引くと、ネットワーク遅延が明らかになります。

  • ss: サーバーが送信されました。リクエスト処理の完了時(レスポンスがクライアントに返送されたとき)にアノテーションが付けられます。このタイムスタンプから sr タイムスタンプを差し引くと、サーバー側がリクエストを処理するのに必要な時間が明らかになります。

  • cr: クライアントを受信しました。スパンの終わりを示します。クライアントはサーバー側からのレスポンスを正常に受信しました。このタイムスタンプから cs タイムスタンプを差し引くと、クライアントがサーバーからのレスポンスを受信するために必要な全体の時間が明らかになります。

次のイメージは、スパントレースがシステムでどのように見えるかを示しています。

Trace Info propagation

メモの各色はスパンを示します(A から G までの 7 つのスパンがあります)。次の注意事項を検討してください。

Trace Id = X
Span Id = D
Client Sent

この注記は、現在のスパンでトレース IDX に設定され、スパン IDD に設定されていることを示しています。また、RPC の観点から、Client Sent イベントが発生しました。

さらにメモを考えてみましょう:

Trace Id = X
Span Id = A
(no custom span)

Trace Id = X
Span Id = C
(custom span)

作成したスパンを続行することも(no custom span 表示の例)、子スパンを手動で作成することもできます(custom span 表示の例)。

次のイメージは、スパンの親子関連がどのように見えるかを示しています。

Parent child relationship

2. 初めての Spring Cloud Sleuth ベースのアプリケーションの開発

このセクションでは、Spring Cloud Sleuth の主な機能の一部を紹介する小さな "Hello World!" Web アプリケーションの開発方法を説明します。ほとんどの IDE でサポートされている Maven を使用してプロジェクトを構築します。トレーサーの実装には、OpenZipkin Brave [GitHub] (英語) を使用します。

start.spring.io に移動し、依存関係検索から "Web" および "Spring Cloud Sleuth" スターターを選択することで、以下の手順をショートカットできます。そうすることで、新しいプロジェクト構造が生成されるため、すぐにコーディング開始できます。

2.1. POM の作成

まず、Maven pom.xml ファイルを作成する必要があります。pom.xml は、プロジェクトのビルドに使用されるレシピです。お気に入りのテキストエディターを開き、次を追加します。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>myproject</artifactId>
    <version>0.0.1-SNAPSHOT</version>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <!-- Use the latest compatible Spring Boot version. You can check https://spring.io/projects/spring-cloud for more information -->
        <version>$2.6.15</version>
    </parent>

    <!-- Spring Cloud Sleuth requires a Spring Cloud BOM -->
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <!-- Provide the latest stable Spring Cloud release train version (e.g. 2020.0.0) -->
                <version>${release.train.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <!-- (you don't need this if you are using a GA version) -->
    <repositories>
        <repository>
            <id>spring-snapshots</id>
            <url>https://repo.spring.io/snapshot</url>
            <snapshots><enabled>true</enabled></snapshots>
        </repository>
        <repository>
            <id>spring-milestones</id>
            <url>https://repo.spring.io/milestone</url>
        </repository>
    </repositories>
    <pluginRepositories>
        <pluginRepository>
            <id>spring-snapshots</id>
            <url>https://repo.spring.io/snapshot</url>
        </pluginRepository>
        <pluginRepository>
            <id>spring-milestones</id>
            <url>https://repo.spring.io/milestone</url>
        </pluginRepository>
    </pluginRepositories>
</project>

上記のリストは、機能するビルドを提供します。mvn package を実行してテストできます(現時点では、「jar は空になります。含めるコンテンツは含まれていません!」という警告は無視できます)。

この時点で、プロジェクトを IDE にインポートできます(ほとんどの最新の Java IDE には Maven の組み込みサポートが含まれています)。簡単にするために、この例では引き続きプレーンテキストエディターを使用します。

2.2. クラスパスの依存関係を追加する

必要な依存関係を追加するには、pom.xml を編集し、parent セクションのすぐ下に spring-boot-starter-web 依存関係を追加します。

<dependencies>
    <!-- Boot's Web support -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- Sleuth with Brave tracer implementation -->
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-sleuth</artifactId>
    </dependency>
</dependencies>

2.3. コードの作成

アプリケーションを完成させるには、単一の Java ファイルを作成する必要があります。デフォルトでは、Maven は src/main/java からソースをコンパイルするため、そのディレクトリ構造を作成してから、src/main/java/Example.java という名前のファイルを追加して、次のコードを含める必要があります。

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.*;
import org.springframework.boot.autoconfigure.*;
import org.springframework.web.bind.annotation.*;

@RestController
@EnableAutoConfiguration
public class Example {

    private static final Logger log = LoggerFactory.getLogger(Example.class);

    @RequestMapping("/")
    String home() {
        log.info("Hello world!");
        return "Hello World!";
    }

    public static void main(String[] args) {
        SpringApplication.run(Example.class, args);
    }

}

ここには多くのコードはありませんが、非常に多くのことが行われています。次のいくつかのセクションで重要な部分を順に説明します。

@RestController および @RequestMapping アノテーション

Spring Boot は RestController をセットアップし、アプリケーションを Tomcat ポートにバインドします。Brave トレーサーを備えた Spring Cloud Sleuth は、受信リクエストのインストルメンテーションを提供します。

2.4. サンプルの実行

この時点で、アプリケーションは動作するはずです。spring-boot-starter-parent POM を使用したため、アプリケーションを開始するために使用できる有用な run ゴールがあります。ルートプロジェクトディレクトリから SPRING_APPLICATION_NAME=backend mvn spring-boot:run と入力して、アプリケーションを起動します。次のような出力が表示されます。

$ mvn spring-boot:run

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 ...
....... . . .
....... . . . (log output here)
....... . . .
........ Started Example in 2.222 seconds (JVM running for 6.514)

Web ブラウザーを localhost:8080 で開くと、次の出力が表示されるはずです。

Hello World!

ログを確認すると、同様の出力が表示されるはずです。

2020-10-21 12:01:16.285  INFO [backend,0b6aaf642574edd3,0b6aaf642574edd3] 289589 --- [nio-9000-exec-1] Example              : Hello world!

ロギングフォーマットが次の情報 [backend,0b6aaf642574edd3,0b6aaf642574edd3 で更新されていることがわかります。このエントリは [application name,trace id, span id] に対応します。アプリケーション名は、SPRING_APPLICATION_NAME 環境変数から読み取られました。

ハンドラーにリクエストを明示的に記録する代わりに、logging.level.org.springframework.web.servlet.DispatcherServlet=DEBUG を設定できます。

アプリケーションを正常に終了するには、ctrl-c を押します。

3. 次のステップ

うまくいけば、このセクションで Spring Cloud Sleuth の基本のいくつかが提供され、独自のアプリケーションを作成するための準備が整いました。開発者のタスク指向型のであれば、spring.io に飛び越えるとのいくつかをチェックアウトする場合があります入門具体的な解決ガイド「Spring でそれを行うにはどうすればよいですか?」問題。また、Spring Cloud Sleuth 固有の「使い方」リファレンスドキュメントもあります。

それ以外の場合、次の論理ステップは Spring Cloud Sleuth の使用を読み取ることです。本当にせっかちな場合は、先に進んで Spring Cloud Sleuth の機能について読むこともできます。

デフォルトのプロジェクトサンプルは samples にあります [GitHub] (英語)