追踪

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

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

支持的追踪器

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

入门

我们需要一个示例应用程序来开始使用追踪。 对于我们的目的，开发您的第一个 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);
	}

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

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

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

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

  • io.opentelemetry:opentelemetry-exporter-zipkin - 将 traces 报告给 Zipkin。

添加以下应用程序属性：

  • Properties

  • 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，后者向 Zipkin 报告一个新的追踪。

现在打开 Zipkin UI（localhost:9411）并点击 "Run Query" 按钮以列出所有收集的追踪。 你应该看到一个追踪。 点击 "Show" 按钮查看该追踪的详细信息。

日志关联 ID

关联 ID 提供了一种有用的方式来将日志文件中的行与 span/trace 链接起来。 如果你使用 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

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

OpenTelemetry 与 Wavefront

使用 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 的报告。

OpenZipkin Brave 与 Zipkin

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

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

  • io.zipkin.reporter2:zipkin-reporter-brave - 向 Zipkin 报告追踪。

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

OpenZipkin Brave 与 Wavefront

使用 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

你可以通过启动一个观测来创建自己的 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 ...
		});
	}

}

这将创建一个名为 "some-operation" 的观测，标签为 "some-tag=some-value"。

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

Baggage

你可以使用 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
		}
	}

}

此示例创建了一个名为 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 会生成一个名为 baggage1 的 MDC 条目。

测试

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