开始

1. Spring Cloud Sleuth 简介

Spring Cloud Sleuth 为 Spring Cloud 提供分布式跟踪解决方案的 API。 它与 OpenZipkin Brave 集成spring-doc.cn

Spring Cloud Sleuth 能够跟踪您的请求和消息，以便您可以将该通信与相应的日志条目相关联。 您还可以将跟踪信息导出到外部系统以可视化延迟。 Spring Cloud Sleuth 直接支持 OpenZipkin 兼容系统。spring-doc.cn

1.1. 术语

Spring Cloud Sleuth 借用了 Dapper 的术语。spring-doc.cn

Span：基本工作单元。 例如，发送 RPC 是一个新的 span，向 RPC 发送响应也是如此。 Span 还具有其他数据，例如描述、带时间戳的事件、键值注释（标签）、导致它们的 Span 的 ID 和进程 ID（通常是 IP 地址）。spring-doc.cn

Span 可以启动和停止，并且它们会跟踪其 timing 信息。 创建 Span 后，必须在将来的某个时间点停止它。spring-doc.cn

跟踪：形成树状结构的一组 span。 例如，如果您运行分布式大数据存储，则跟踪可能由请求形成。PUTspring-doc.cn

注释/事件：用于及时记录事件的存在。spring-doc.cn

从概念上讲，在典型的 RPC 场景中，我们标记这些事件以突出显示发生的操作类型 （这并不意味着物理上将在 span） 上设置此类事件。spring-doc.cn

  • cs：客户端已发送。 客户端已发出请求。 此注释指示 span 的开始。spring-doc.cn

  • sr： Server Received： 服务端收到请求并开始处理。 从此时间戳中减去时间戳可显示网络延迟。csspring-doc.cn

  • ss：服务器已发送。 在请求处理完成时进行批注（当响应被发送回客户端时）。 从此时间戳中减去时间戳可显示服务器端处理请求所需的时间。srspring-doc.cn

  • cr：已接收客户端。 表示 span 的结束。 客户端已成功收到来自服务器端的响应。 从此时间戳中减去时间戳可显示客户端从服务器接收响应所需的全部时间。csspring-doc.cn

下图显示了 Span 和 Trace 在系统中的外观。spring-doc.cn

跟踪信息传播

音符的每种颜色都表示一个跨度（有七个跨度 - 从 A 到 G）。 请考虑以下说明：spring-doc.cn

Trace Id = X
Span Id = D
Client Sent

此说明表示当前 span 的 Trace Id 设置为 X，Span Id 设置为 D。 此外，从 RPC 的角度来看，事件确实发生了。Client Sentspring-doc.cn

让我们考虑更多注意事项：spring-doc.cn

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

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

您可以继续使用创建的 span （带指示的示例），也可以手动创建子 span （带指示的示例）。no custom spancustom spanspring-doc.cn

下图显示了 Span 的父子关系的外观：spring-doc.cn

父子关系

2. 开发您的第一个基于 Spring Cloud 侦探的应用程序

本节介绍如何开发一个小型的 “Hello World！” Web 应用程序，该应用程序重点介绍了 Spring Cloud Sleuth 的一些主要功能。 我们使用 Maven 来构建这个项目，因为大多数 IDE 都支持它。 作为跟踪器实现，我们将使用 OpenZipkin Brave。spring-doc.cn

您可以通过转到 start.spring.io 并从依赖项搜索器中选择“Web”和“Spring Cloud Sleuth”Starters来简化以下步骤。 这样做会生成一个新的项目结构，以便您可以立即开始编码。spring-doc.cn

2.1. 创建 POM

我们需要从创建一个 Maven 文件开始。 这是用于构建项目的配方。 打开您最喜欢的文本编辑器并添加以下内容：pom.xmlpom.xmlspring-doc.cn

<?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.4.10</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>

前面的清单应该为您提供一个有效的版本。 您可以通过运行来测试它（现在，您可以忽略 “jar will be empty - no content was marked for inclusion！” 警告）。mvn packagespring-doc.cn

此时，您可以将项目导入到 IDE 中（大多数现代 Java IDE 都包含对 Maven 的内置支持）。 为简单起见，我们在此示例中继续使用纯文本编辑器。

2.2. 添加 Classpath 依赖项

要添加必要的依赖项，请编辑 your 并在该部分的正下方添加依赖项：pom.xmlspring-boot-starter-webparentspring-doc.cn

<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/javasrc/main/java/Example.javaspring-doc.cn

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(Backend.class);

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

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

}

虽然这里没有太多代码，但有很多事情要做。 在接下来的几节中，我们将逐步介绍重要部分。spring-doc.cn

@RestController 和 @RequestMapping 注释

Spring Boot 设置 Rest Controller 并使我们的应用程序绑定到 Tomcat 端口。 带有 Brave tracer 的 Spring Cloud Sleuth 将提供传入请求的检测。spring-doc.cn

2.4. 运行示例

此时，您的应用程序应该可以正常工作。 由于您使用了 POM，因此您有一个有用的目标，可用于启动应用程序。 键入 from the root project directory 以启动应用程序。 您应该会看到类似于以下内容的输出：spring-boot-starter-parentrunSPRING_APPLICATION_NAME=backend mvn spring-boot:runspring-doc.cn

$ mvn spring-boot:run

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

如果打开 Web 浏览器，您应该会看到以下输出：localhost:8080spring-doc.cn

Hello World!

如果您检查日志，您应该会看到类似的输出spring-doc.cn

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_NAMEspring-doc.cn

您可以将 .logging.level.org.springframework.web.servlet.DispatcherServlet=DEBUG

要正常退出应用程序，请按 。ctrl-cspring-doc.cn

3. 后续步骤

希望本节提供了一些 Spring Cloud Sleuth 基础知识，并帮助您编写自己的应用程序。 如果你是一个面向任务的开发人员类型，你可能想跳到 spring.io 并查看一些解决特定 “如何使用 Spring 实现该操作 ”问题的入门指南。 我们还有特定于 Spring Cloud Sleuth 的“操作方法”参考文档。spring-doc.cn

否则，下一个逻辑步骤是阅读 Using Spring Cloud Sleuth。 如果你真的没有耐心，你也可以跳到前面，阅读 Spring Cloud Sleuth 功能。spring-doc.cn

您可以在 samples 中找到默认项目示例。spring-doc.cn