描图 (Tracing) _ Spring Boot3.4.0-SNAPSHOT中文文档(官方文档中文翻译)|Spring 教程 —

此版本仍在开发中，尚未被视为稳定版本。对于最新的稳定版本，请使用 Spring Boot 3.3.4！spring-doc.cn

Spring Boot Actuator 为 Micrometer Tracing 提供依赖项管理和自动配置，Micrometer Tracing是流行的 Tracer 库的门面。spring-doc.cn

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

支持的 Tracer

Spring Boot 为以下跟踪器提供自动配置：spring-doc.cn

使用 Zipkin、Wavefront 或 OTLP 的 OpenTelemetry spring-doc.cn
OpenZipkin Brave 与 Zipkin 或 Wavefront spring-doc.cn

开始

我们需要一个示例应用程序，我们可以使用它来开始跟踪。就我们的目的而言，开发您的第一个 Spring Boot 应用程序中介绍的简单 “Hello World！” Web 应用程序就足够了。我们将使用 OpenTelemetry 跟踪器，并将 Zipkin 作为跟踪后端。spring-doc.cn

概括地说，我们的主要应用程序代码如下所示：spring-doc.cn

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);
	}

}

该方法中添加了一个 logger 语句，这在后面会很重要。home()

现在我们必须添加以下依赖项：spring-doc.cn

org.springframework.boot:spring-boot-starter-actuatorspring-doc.cn
io.micrometer:micrometer-tracing-bridge-otel- 将 Micrometer Observation API 桥接到 OpenTelemetry。spring-doc.cn
io.opentelemetry:opentelemetry-exporter-zipkin- 向 Zipkin 报告跟踪。spring-doc.cn

添加以下应用程序属性：spring-doc.cn

Propertiesspring-doc.cn
YAMLspring-doc.cn

management.tracing.sampling.probability=1

management:
  tracing:
    sampling:
      probability: 1.0

默认情况下， Spring Boot 仅对 10% 的请求进行采样，以防止跟踪后端不堪重负。此属性将其切换到 100%，以便将每个请求发送到跟踪后端。spring-doc.cn

为了收集和可视化跟踪，我们需要一个正在运行的跟踪后端。我们在这里使用 Zipkin 作为跟踪后端。 Zipkin 快速入门指南提供了如何在本地启动 Zipkin 的说明。spring-doc.cn

Zipkin 运行后，您可以启动应用程序。spring-doc.cn

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

Hello World!

在幕后，已经为 HTTP 请求创建了一个观察结果，该请求又桥接到 OpenTelemetry，后者向 Zipkin 报告新的跟踪。spring-doc.cn

现在打开 Zipkin UI 并按“Run Query”按钮列出所有收集的跟踪。您应该会看到一条跟踪。按 “Show” 按钮查看该跟踪的详细信息。localhost:9411spring-doc.cn

该方法中添加了一个 logger 语句，这在后面会很重要。home()

记录关联 ID

相关 ID 提供了一种将日志文件中的行链接到 span/traces 的有用方法。如果您使用的是 Micrometer Tracing，则默认情况下， Spring Boot 将在日志中包含相关 ID。spring-doc.cn

默认相关 ID 是根据 MDC 值构建的。例如，如果 Micrometer Tracing 添加了 MDC 和 MDC 的日志输出将包含相关 ID 。traceIdspanIdtraceId803B448A0489F84084905D3093480352spanId3425F23BB2432450[803B448A0489F84084905D3093480352-3425F23BB2432450]spring-doc.cn

如果您希望对相关 ID 使用不同的格式，则可以使用该属性来定义一个格式。例如，以下内容将以 Spring Cloud Sleuth 以前使用的格式为 Logback 提供相关 ID：logging.pattern.correlationspring-doc.cn

Propertiesspring-doc.cn
YAMLspring-doc.cn

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

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

在上面的示例中，设置为以避免应用程序名称在日志消息中重复（已包含它）。还值得一提的是，它包含一个尾随空格，因此默认情况下它与紧随其后的 Logger 名称分开。logging.include-application-namefalselogging.pattern.correlationlogging.pattern.correlation

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

传播跟踪

要通过网络自动传播跟踪，请使用自动配置的 RestTemplateBuilder、RestClient.Builder 或 WebClient.Builder 来构建客户端。spring-doc.cn

如果您在不使用自动配置的生成器的情况下创建、或，则自动跟踪传播将不起作用！RestTemplateRestClientWebClient

Tracer 实现

由于 Micrometer Tracer 支持多个 tracer 实现，因此 Spring Boot 可以有多种依赖项组合。spring-doc.cn

所有 tracer 实现都需要 dependency。org.springframework.boot:spring-boot-starter-actuatorspring-doc.cn

使用 Zipkin 的 OpenTelemetry

使用 OpenTelemetry 进行跟踪并向 Zipkin 报告需要以下依赖项：spring-doc.cn

io.micrometer:micrometer-tracing-bridge-otel- 将 Micrometer Observation API 桥接到 OpenTelemetry。spring-doc.cn
io.opentelemetry:opentelemetry-exporter-zipkin- 向 Zipkin 报告跟踪。spring-doc.cn

使用配置属性配置向 Zipkin 报告。management.zipkin.tracing.*spring-doc.cn

带有 Wavefront 的 OpenTelemetry

使用 OpenTelemetry 进行跟踪并向 Wavefront 报告需要以下依赖项：spring-doc.cn

io.micrometer:micrometer-tracing-bridge-otel- 将 Micrometer Observation API 桥接到 OpenTelemetry。spring-doc.cn
io.micrometer:micrometer-tracing-reporter-wavefront- 向 Wavefront 报告跟踪。spring-doc.cn

使用配置属性配置向 Wavefront 报告。management.wavefront.*spring-doc.cn

使用 OTLP 的 OpenTelemetry

使用 OpenTelemetry 进行跟踪和使用 OTLP 进行报告需要以下依赖项：spring-doc.cn

io.micrometer:micrometer-tracing-bridge-otel- 将 Micrometer Observation API 桥接到 OpenTelemetry。spring-doc.cn
io.opentelemetry:opentelemetry-exporter-otlp- 将跟踪报告给可以接受 OTLP 的收集器。spring-doc.cn

使用配置属性来配置使用 OTLP 的报告。management.otlp.tracing.*spring-doc.cn

OpenZipkin Brave 与 Zipkin

使用 OpenZipkin Brave 进行跟踪并向 Zipkin 报告需要以下依赖项：spring-doc.cn

io.micrometer:micrometer-tracing-bridge-brave- 将 Micrometer Observation API 桥接到 Brave。spring-doc.cn
io.zipkin.reporter2:zipkin-reporter-brave- 向 Zipkin 报告跟踪。spring-doc.cn

使用配置属性配置向 Zipkin 报告。management.zipkin.tracing.*spring-doc.cn

OpenZipkin Brave 与 Wavefront

使用 OpenZipkin Brave 进行跟踪并向 Wavefront 报告需要以下依赖项：spring-doc.cn

io.micrometer:micrometer-tracing-bridge-brave- 将 Micrometer Observation API 桥接到 Brave。spring-doc.cn
io.micrometer:micrometer-tracing-reporter-wavefront- 向 Wavefront 报告跟踪。spring-doc.cn

使用配置属性配置向 Wavefront 报告。management.wavefront.*spring-doc.cn

与 Micrometer Observation 集成

A 会自动注册到上，这将为每个已完成的观测值创建跨度。TracingAwareMeterObservationHandlerObservationRegistryspring-doc.cn

创建自定义 Span

您可以通过开始观察来创建自己的范围。为此，请注入到你的组件中：ObservationRegistryspring-doc.cn

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 ...
		});
	}

}

这将创建一个名为 “some-operation” 的观察，其标签为 “some-tag=some-value”。spring-doc.cn

如果要在不创建指标的情况下创建 span，则需要使用 Micrometer 的较低级别 Tracer API。

行李

您可以使用 API 创建行李：Tracerspring-doc.cn

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
		}
	}

}

此示例创建以值 . 如果你使用的是 W3C 传播，那么 Baggage 会自动通过网络传播。如果您使用的是 B3 传播，则不会自动传播 baggage。要在网络上手动传播 Baggage，请使用 configuration 属性（这也适用于 W3C）。在上面的示例中，将此属性设置为会导致 HTTP 标头。baggage1value1management.tracing.baggage.remote-fieldsbaggage1baggage1: value1spring-doc.cn

如果要将 baggage 传播到 MDC，请使用 configuration 属性。在上面的示例中，将此属性设置为将导致名为的 MDC 条目。management.tracing.baggage.correlation.fieldsbaggage1baggage1spring-doc.cn

测试

使用时，不会自动配置报告数据的跟踪组件。有关更多详细信息，请参阅使用跟踪。@SpringBootTestspring-doc.cn