Spring Boot 中的 Sleuth 是什么, 如何使用

article/2025/9/20 21:56:10

Spring Boot 是一个非常流行的 Java Web 开发框架，它提供了许多方便的功能，其中之一就是 Sleuth。Sleuth 是一个分布式跟踪系统，用于跟踪应用程序中的请求和操作。在本文中，我们将探讨 Spring Boot 中的 Sleuth 是什么，以及如何使用它来跟踪应用程序中的请求和操作。

在这里插入图片描述

什么是 Sleuth？

Sleuth 是一个分布式跟踪系统，用于跟踪应用程序中的请求和操作。它可以帮助我们了解应用程序的结构和性能，并定位问题的根本原因。Sleuth 可以与 Zipkin 等分布式跟踪系统配合使用，从而提供更全面的应用程序跟踪和分析功能。

Sleuth 在 Spring Boot 中提供了一个便捷的集成方式。它可以轻松地跟踪应用程序中的请求和操作，并将跟踪信息记录到日志文件中。这使得我们可以更轻松地了解应用程序的结构和性能，并快速定位问题的根本原因。

Sleuth 的核心概念

在使用 Sleuth 之前，我们需要了解一些核心概念：

Trace（跟踪）：一个 Trace 表示一个请求或操作的完整的调用链，从客户端发起请求开始，到服务端响应请求结束。
Span（跨度）：一个 Span 表示一个请求或操作的一部分，它包含了一些有用的信息，如开始时间、结束时间、操作名称等。
Trace ID（跟踪 ID）：一个 Trace ID 是一个唯一的标识符，它用于将一组 Span 关联在一起，形成一个完整的 Trace。
Span ID（跨度 ID）：一个 Span ID 是一个唯一的标识符，它用于标识一个 Span。

在 Sleuth 中，每个请求或操作都会生成一个 Trace，并且每个 Trace 包含多个 Span。每个 Span 包含一个唯一的 Span ID，并与一个 Trace ID 相关联。通过 Trace ID 和 Span ID，我们可以将多个 Span 关联在一起，形成一个完整的 Trace。

使用 Sleuth

要使用 Sleuth，我们需要将 Sleuth 依赖添加到项目中。在 Maven 项目中，可以在 pom.xml 文件中添加以下依赖：

<dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-starter-sleuth</artifactId>
</dependency>

在 Gradle 项目中，可以在 build.gradle 文件中添加以下依赖：

implementation 'org.springframework.cloud:spring-cloud-starter-sleuth'

添加依赖后，Sleuth 就会自动启用，并开始跟踪应用程序中的请求和操作。Sleuth 会自动为每个请求或操作生成一个 Trace，并为每个 Trace 中的每个 Span 生成一个唯一的 Span ID。

默认情况下，Sleuth 会将 Trace ID 和 Span ID 添加到日志中，以便我们可以轻松地跟踪应用程序中的请求和操作。例如，下面是一个包含 Trace ID 和 Span ID 的日志：

2021-09-01 12:00:00.000 [my-service,0123456789abcdef,0123456789abcdef,true] TRACE [MyController] - Handling request

在上面的例子中，日志中包含了一个 Trace ID（0123456789abcdef）和一个 Span ID（0123456789abcdef），它们分别与一个名为 my-service 的服务相关联。

自定义 Sleuth 配置

在使用 Sleuth 时，我们可以通过配置文件或编程方式进行自定义配置。以下是一些常用的自定义配置方式：

配置 Trace 和 Span 的名称

默认情况下，Sleuth 会为每个 Trace 和Span 分别使用应用程序的名称和随机生成的 ID。如果需要自定义 Trace 和 Span 的名称，可以在 application.properties（或 application.yaml）文件中添加以下配置：

spring.sleuth.sampler.probability=1.0
spring.application.name=my-custom-app-name
spring.sleuth.span-name-regex=(?<controller>MyController)

上面的配置将会将 Trace 的名称设置为 my-custom-app-name，将所有包含 MyController 的 Span 设置为 MyController。同时，spring.sleuth.sampler.probability=1.0 确保 Sleuth 对所有请求和操作进行跟踪。

配置 Sleuth 的 Sampler

在实际的生产环境中，我们可能需要对请求和操作进行采样，以避免 Sleuth 产生过多的跟踪数据。在 Sleuth 中，采样是通过 Sampler 实现的。默认情况下，Sleuth 使用一个随机采样器，它对 10% 的请求进行采样。

如果需要自定义采样器，可以在配置文件中添加以下配置：

spring.sleuth.sampler.type=RATE_LIMITED
spring.sleuth.sampler.rate=0.5

上面的配置将会将采样器设置为 RATE_LIMITED，它会根据请求速率限制采样率。具体而言，它将对 50% 的请求进行采样。

使用 MDC（Mapped Diagnostic Context）

在实际的生产环境中，我们可能需要将 Trace 和 Span 的信息传递给 Logback 或 Log4j2 等日志框架。为了实现这一点，Sleuth 提供了一个 MDC（Mapped Diagnostic Context）实现，它可以将 Trace 和 Span 的信息添加到日志中。

要使用 MDC，我们需要在 application.properties（或 application.yaml）文件中添加以下配置：

logging.pattern.level=%X{traceId} %X{spanId} %5p [${spring.zipkin.service.name:-},%X{X-B3-TraceId:-},%X{X-B3-SpanId:-},%X{X-Span-Export:-}] [%t] %logger{5} - %msg%n

上面的配置将在日志模式中添加 Trace 和 Span 的信息。这样，我们就可以轻松地跟踪应用程序中的请求和操作，并将跟踪信息添加到日志中。