追踪

DeepSeek V3 中英对照 Tracing

Spring Boot Actuator 提供了对 Micrometer Tracing 的依赖管理和自动配置，Micrometer Tracing 是一个用于流行追踪库的门面（facade）。

提示

要了解有关 Micrometer Tracing 功能的更多信息，请参阅其参考文档。

支持的追踪器

Spring Boot 为以下追踪器提供了自动配置：

• OpenTelemetry 与 Zipkin、Wavefront 或 OTLP 结合使用

• OpenZipkin Brave 与 Zipkin 或 Wavefront 结合使用

入门指南

我们需要一个示例应用程序来开始使用追踪功能。为了达到我们的目的，开发你的第一个 Spring Boot 应用程序 部分中介绍的简单的 “Hello World!” Web 应用程序就足够了。我们将使用 OpenTelemetry 追踪器，并以 Zipkin 作为追踪后端。

回顾一下，我们的主应用程序代码如下所示：

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@SpringBootApplication
public class MyApplication {

    private static final Log logger = LogFactory.getLog(MyApplication.class);

    @RequestMapping("/")
    String home() {
        logger.info("home() has been called");
        return "Hello World!";
    }

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

}

java

备注

在 home() 方法中添加了一个日志记录语句，这在后面会很重要。

现在我们需要添加以下依赖项：

• org.springframework.boot:spring-boot-starter-actuator

• io.micrometer:micrometer-tracing-bridge-otel - 将 Micrometer Observation API 桥接到 OpenTelemetry。

• io.opentelemetry:opentelemetry-exporter-zipkin - 将追踪数据报告给 Zipkin。

添加以下应用程序属性：

Properties

management.tracing.sampling.probability=1

properties

YAML

management:
  tracing:
    sampling:
      probability: 1.0

yaml

默认情况下，Spring Boot 仅对 10% 的请求进行采样，以防止对追踪后端造成过大压力。该属性将其切换为 100%，以便将每个请求都发送到追踪后端。

为了收集和可视化跟踪数据，我们需要一个运行中的跟踪后端。在这里，我们使用 Zipkin 作为我们的跟踪后端。Zipkin 快速入门指南 提供了在本地启动 Zipkin 的指导说明。

在 Zipkin 运行后，您可以启动您的应用程序。

如果你在网页浏览器中打开 [localhost:8080](http://localhost:8080)，你应该会看到以下输出：

Hello World!

none

在幕后，已经为 HTTP 请求创建了一个观测（observation），随后它被桥接到 OpenTelemetry，再由 OpenTelemetry 向 Zipkin 报告一个新的追踪（trace）。

现在在 [localhost:9411](http://localhost:9411) 打开 Zipkin UI，然后点击 "Run Query" 按钮以列出所有收集到的跟踪信息。你应该会看到一条跟踪记录。点击 "Show" 按钮以查看该跟踪的详细信息。

日志关联 ID

关联 ID 提供了一种有用的方式，将日志文件中的行与跟踪/跨度关联起来。如果你正在使用 Micrometer Tracing，Spring Boot 默认会在日志中包含关联 ID。

默认的关联 ID 是由 traceId 和 spanId MDC 值构建的。例如，如果 Micrometer Tracing 添加了一个 MDC traceId 为 803B448A0489F84084905D3093480352 和一个 MDC spanId 为 3425F23BB2432450，那么日志输出将包含关联 ID [803B448A0489F84084905D3093480352-3425F23BB2432450]。

如果您希望为关联 ID 使用不同的格式，可以使用 logging.pattern.correlation 属性来定义。例如，以下配置将为 Logback 提供 Spring Cloud Sleuth 之前使用的格式的关联 ID：

Properties

logging.pattern.correlation=[${spring.application.name:},%X{traceId:-},%X{spanId:-}] 
logging.include-application-name=false

properties

YAML

logging:
  pattern:
    correlation: "[${spring.application.name:},%X{traceId:-},%X{spanId:-}] "
  include-application-name: false

yaml

备注

在上面的示例中，logging.include-application-name 被设置为 false，以避免应用程序名称在日志消息中重复出现（logging.pattern.correlation 已经包含了它）。值得一提的是，logging.pattern.correlation 包含一个尾随空格，这样它就可以与默认紧随其后的日志记录器名称分隔开来。

提示

关联 ID 依赖于上下文传播。请阅读此文档以了解更多详情。

传播跟踪

要在网络上自动传播跟踪，可以使用自动配置的 RestTemplateBuilder、RestClient.Builder 或 WebClient.Builder 来构建客户端。

注意

如果你在没有使用自动配置的构建器的情况下创建了 RestTemplate、RestClient 或 WebClient，自动的追踪传播将无法工作！

Tracer 实现

由于 Micrometer Tracer 支持多种追踪器实现，因此在 Spring Boot 中有多种可能的依赖组合。

所有的追踪器实现都需要 org.springframework.boot:spring-boot-starter-actuator 依赖。

OpenTelemetry 与 Zipkin

使用 OpenTelemetry 进行追踪并报告到 Zipkin 需要以下依赖项：

• io.micrometer:micrometer-tracing-bridge-otel - 将 Micrometer Observation API 桥接到 OpenTelemetry。

• io.opentelemetry:opentelemetry-exporter-zipkin - 将跟踪数据报告到 Zipkin。

使用 management.zipkin.tracing.* 配置属性来配置向 Zipkin 报告。

使用 Wavefront 的 OpenTelemetry

使用 OpenTelemetry 进行追踪并将数据报告到 Wavefront 需要以下依赖项：

• io.micrometer:micrometer-tracing-bridge-otel - 将 Micrometer Observation API 桥接到 OpenTelemetry。

• io.micrometer:micrometer-tracing-reporter-wavefront - 将跟踪数据报告到 Wavefront。

使用 management.wavefront.* 配置属性来配置向 Wavefront 的报告。

OpenTelemetry 与 OTLP

使用 OpenTelemetry 进行追踪并通过 OTLP 进行报告需要以下依赖项：

• io.micrometer:micrometer-tracing-bridge-otel - 将 Micrometer Observation API 桥接到 OpenTelemetry。

• io.opentelemetry:opentelemetry-exporter-otlp - 将跟踪数据报告给可以接受 OTLP 的收集器。

使用 management.otlp.tracing.* 配置属性来配置通过 OTLP 进行报告。

使用 Zipkin 的 OpenZipkin Brave

使用 OpenZipkin Brave 进行追踪并报告到 Zipkin 需要以下依赖：

• io.micrometer:micrometer-tracing-bridge-brave - 将 Micrometer Observation API 桥接到 Brave。

• io.zipkin.reporter2:zipkin-reporter-brave - 将追踪数据报告给 Zipkin。

使用 management.zipkin.tracing.* 配置属性来配置向 Zipkin 的报告。

使用 Wavefront 的 OpenZipkin Brave

使用 OpenZipkin Brave 进行追踪并将数据报告到 Wavefront 需要以下依赖项：

• io.micrometer:micrometer-tracing-bridge-brave - 将 Micrometer Observation API 桥接到 Brave。

• io.micrometer:micrometer-tracing-reporter-wavefront - 将跟踪数据报告到 Wavefront。

使用 management.wavefront.* 配置属性来配置向 Wavefront 报告。

与 Micrometer Observation 的集成

一个 TracingAwareMeterObservationHandler 会自动注册在 ObservationRegistry 上，它为每个完成的观察创建 span。

创建自定义 Span

你可以通过启动一个观测来创建自己的跨度。为此，将 ObservationRegistry 注入到你的组件中：

import io.micrometer.observation.Observation;
import io.micrometer.observation.ObservationRegistry;

import org.springframework.stereotype.Component;

@Component
class CustomObservation {

    private final ObservationRegistry observationRegistry;

    CustomObservation(ObservationRegistry observationRegistry) {
        this.observationRegistry = observationRegistry;
    }

    void someOperation() {
        Observation observation = Observation.createNotStarted("some-operation", this.observationRegistry);
        observation.lowCardinalityKeyValue("some-tag", "some-value");
        observation.observe(() -> {
            // Business logic ...
        });
    }

}

java

这将创建一个名为 "some-operation" 的观察项，并带有标签 "some-tag=some-value"。

提示

如果你想创建一个 span 而不创建指标，你需要使用 Micrometer 的底层 Tracer API。

行李

你可以使用 Tracer API 来创建 baggage：

import io.micrometer.tracing.BaggageInScope;
import io.micrometer.tracing.Tracer;

import org.springframework.stereotype.Component;

@Component
class CreatingBaggage {

    private final Tracer tracer;

    CreatingBaggage(Tracer tracer) {
        this.tracer = tracer;
    }

    void doSomething() {
        try (BaggageInScope scope = this.tracer.createBaggageInScope("baggage1", "value1")) {
            // Business logic
        }
    }

}

java

这个示例创建了一个名为 baggage1 的 baggage，其值为 value1。如果你使用的是 W3C 传播，baggage 会自动通过网络传播。如果你使用的是 B3 传播，baggage 不会自动传播。要手动通过网络传播 baggage，可以使用 management.tracing.baggage.remote-fields 配置属性（这也适用于 W3C）。对于上述示例，将此属性设置为 baggage1 会导致生成一个 HTTP 头 baggage1: value1。

如果你想将 baggage 传播到 MDC，可以使用 management.tracing.baggage.correlation.fields 配置属性。对于上面的例子，将此属性设置为 baggage1 将会在 MDC 中创建一个名为 baggage1 的条目。

测试

在使用 @SpringBootTest 时，报告数据的追踪组件不会自动配置。更多详情请参见使用追踪。