跟踪

Spring Boot Actuator 为 Micrometer Tracing（一个流行追踪器库的门面）提供依赖管理和自动配置。

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

支持的追踪器

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

OpenTelemetry 与 Zipkin 或 OTLP。
OpenZipkin Brave 与 Zipkin。

入门

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

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

Java
Kotlin

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

}

import org.apache.commons.logging.Log
import org.apache.commons.logging.LogFactory
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController

@RestController
@SpringBootApplication
class MyApplication {

	private val logger: Log = LogFactory.getLog(MyApplication::class.java)

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

}

fun main(args: Array<String>) {
	runApplication<MyApplication>(*args)
}

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

现在我们必须添加以下依赖项：

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

添加以下应用程序属性：

属性
YAML

management.tracing.sampling.probability=1

management:
  tracing:
    sampling:
      probability: 1.0

默认情况下，Spring Boot 只对 10% 的请求进行抽样，以防止追踪后端不堪重负。此属性将其切换为 100%，以便每个请求都发送到追踪后端。

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

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

如果您在 Web 浏览器中打开 localhost:8080，您应该会看到以下输出

Hello World!

在幕后，已经为 HTTP 请求创建了一个观察，该观察又桥接到 OpenTelemetry，OpenTelemetry 将新的追踪报告给 Zipkin。

现在打开 Zipkin UI (localhost:9411) 并点击“运行查询”按钮列出所有收集到的追踪。您应该会看到一个追踪。点击“显示”按钮查看该追踪的详细信息。

日志关联 ID

关联 ID 提供了一种有用的方式，可以将日志文件中的行链接到 span/追踪。如果您正在使用 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：

属性
YAML

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

在上面的示例中，logging.include-application-name 设置为 false 以避免应用程序名称在日志消息中重复（logging.pattern.correlation 已包含它）。还需要提及的是，logging.pattern.correlation 包含一个尾随空格，以便它与默认紧随其后的日志记录器名称分开。

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

传播追踪

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

如果您在不使用自动配置的构建器的情况下创建 RestTemplate、RestClient 或 WebClient，自动追踪传播将不起作用！

追踪器实现

由于 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.tracing.export.zipkin.* 配置属性来配置向 Zipkin 报告。

OpenTelemetry 与 OTLP

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

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

使用 management.opentelemetry.tracing.export.otlp.* 配置属性来配置使用 OTLP 报告。

如果需要对 OTLP span 导出器进行高级自定义，请考虑注册 OtlpHttpSpanExporterBuilderCustomizer 或 OtlpGrpcSpanExporterBuilderCustomizer bean。这些将在创建 OtlpHttpSpanExporter 或 OtlpGrpcSpanExporter 之前调用。自定义器优先于自动配置应用的任何内容。

OpenZipkin Brave 与 Zipkin

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

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

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

与 Micrometer Observation 集成

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

创建自定义 Span

您可以通过启动观察来创建自己的 span。为此，将 ObservationRegistry 注入到您的组件中：

Java
Kotlin

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

}

import io.micrometer.observation.Observation
import io.micrometer.observation.ObservationRegistry
import org.springframework.stereotype.Component

@Component
class CustomObservation(private val observationRegistry: ObservationRegistry) {

	fun someOperation() {
		Observation.createNotStarted("some-operation", observationRegistry)
			.lowCardinalityKeyValue("some-tag", "some-value")
			.observe {
				// Business logic ...
			}
	}

}

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

如果您想创建 span 而不创建指标，则需要使用 Micrometer 的低级 Tracer API。

Baggage

您可以使用 Tracer API 创建 baggage

Java
Kotlin

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

}

import io.micrometer.tracing.Tracer
import org.springframework.stereotype.Component

@Component
class CreatingBaggage(private val tracer: Tracer) {

	fun doSomething() {
		tracer.createBaggageInScope("baggage1", "value1").use {
			// Business logic
		}
	}

}

此示例创建名为 baggage1 且值为 value1 的 baggage。如果您使用 W3C 传播，该 baggage 会自动通过网络传播。如果您使用 B3 传播，则 baggage 不会自动传播。要手动通过网络传播 baggage，请使用 management.tracing.baggage.remote-fields 配置属性（这也适用于 W3C）。对于上面的示例，将此属性设置为 baggage1 会生成 HTTP 头 baggage1: value1。

如果您想将 baggage 传播到 MDC，请使用 management.tracing.baggage.correlation.fields 配置属性。对于上面的示例，将此属性设置为 baggage1 会生成一个名为 baggage1 的 MDC 条目。

测试

使用 @SpringBootTest 时，不会自动配置报告数据的追踪组件。有关详细信息，请参阅使用追踪。