Tracing

Spring Boot Actuator 为 Micrometer Tracing 提供了依赖项管理和自动配置，这是流行的跟踪程序库的框架。

Spring Boot Actuator provides dependency management and auto-configuration for Micrometer Tracing, a facade for popular tracer libraries.

要详细了解 Micrometer 跟踪功能，请参阅其 reference documentation。

To learn more about Micrometer Tracing capabilities, see its reference documentation.

Supported Tracers

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

Spring Boot ships auto-configuration for the following tracers:

Getting Started

我们需要一个示例应用程序来开始跟踪。对于我们的目的，“Developing Your First Spring Boot Application” 部分中涵盖的简单 “Hello World!” Web 应用程序就足够了。我们将使用带有 Zipkin 的 OpenTelemetry 跟踪器作为跟踪后端。

We need an example application that we can use to get started with tracing. For our purposes, the simple “Hello World!” web application that’s covered in the “Developing Your First Spring Boot Application” section will suffice. We’re going to use the OpenTelemetry tracer with Zipkin as trace backend.

总而言之，我们的主应用程序代码如下所示：

To recap, our main application code looks like this:

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

There’s an added logger statement in the home() method, which will be important later.

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

Now we have to add the following dependencies:

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

  • io.micrometer:micrometer-tracing-bridge-otel - bridges the Micrometer Observation API to OpenTelemetry.

  • io.opentelemetry:opentelemetry-exporter-zipkin - reports traces to Zipkin.

添加以下应用程序属性：

Add the following application properties:

management:
  tracing:
    sampling:
      probability: 1.0

默认情况下，Spring Boot 仅对 10% 的请求进行采样，以防止压垮跟踪后端。此属性将其切换到 100%，以便将每个请求发送到跟踪后端。

By default, Spring Boot samples only 10% of requests to prevent overwhelming the trace backend. This property switches it to 100% so that every request is sent to the trace backend.

要收集和可视化跟踪，我们需要一个正在运行的跟踪后端。我们在此使用 Zipkin 作为跟踪后端。 Zipkin Quickstart guide提供有关如何本地启动 Zipkin 的说明。

To collect and visualize the traces, we need a running trace backend. We use Zipkin as our trace backend here. The Zipkin Quickstart guide provides instructions how to start Zipkin locally.

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

After Zipkin is running, you can start your application.

如果你用网络浏览器打开 http://localhost:8080，你应该会看到以下输出：

If you open a web browser to http://localhost:8080, you should see the following output:

Hello World!

在后台，已经为 HTTP 请求创建了一个观测，该观测又会桥接到 OpenTelemetry，后者会向 Zipkin 报告一个新的跟踪。

Behind the scenes, an observation has been created for the HTTP request, which in turn gets bridged to OpenTelemetry, which reports a new trace to Zipkin.

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

Now open the Zipkin UI at http://localhost:9411 and press the "Run Query" button to list all collected traces. You should see one trace. Press the "Show" button to see the details of that trace.

Logging Correlation IDs

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

Correlation IDs provide a helpful way to link lines in your log files to spans/traces. If you are using Micrometer Tracing, Spring Boot will include correlation IDs in your logs by default.

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

The default correlation ID is built from traceId and spanId MDC values. For example, if Micrometer Tracing has added an MDC traceId of 803B448A0489F84084905D3093480352 and an MDC spanId of 3425F23BB2432450 the log output will include the correlation ID [803B448A0489F84084905D3093480352-3425F23BB2432450].

如果您更喜欢为关联 ID 使用其他格式，则可以使用`configprop:logging.pattern.correlation[]`属性定义一个。例如，以下内容将为 Logback 提供关联 ID，采用 Spring Cloud Sleuth 之前使用的格式：

If you prefer to use a different format for your correlation ID, you can use the configprop:logging.pattern.correlation[] property to define one. For example, the following will provide a correlation ID for Logback in format previously used by Spring Cloud Sleuth:

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

在上面的示例中，将`configprop:logging.include-application-name[]`设置为 false，以避免在日志消息中重复出现应用程序名称（`configprop:logging.pattern.correlation[]`已包含它）。同样值得注意的是，`configprop:logging.pattern.correlation[]`包含一个尾随空格，以便它默认与紧随其后的记录器名称分开。

In the example above, configprop:logging.include-application-name[] is set to false to avoid the application name being duplicated in the log messages (configprop:logging.pattern.correlation[] already contains it). It’s also worth mentioning that configprop:logging.pattern.correlation[] contains a trailing space so that it is separated from the logger name that comes right after it by default.

Propagating Traces

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

To automatically propagate traces over the network, use the auto-configured RestTemplateBuilder or WebClient.Builder to construct the client.

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

If you create the WebClient or the RestTemplate without using the auto-configured builders, automatic trace propagation won’t work!

Tracer Implementations

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

As Micrometer Tracer supports multiple tracer implementations, there are multiple dependency combinations possible with Spring Boot.

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

All tracer implementations need the org.springframework.boot:spring-boot-starter-actuator dependency.

OpenTelemetry With Zipkin

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

Tracing with OpenTelemetry and reporting to Zipkin requires the following dependencies:

  • io.micrometer:micrometer-tracing-bridge-otel - bridges the Micrometer Observation API to OpenTelemetry.

  • io.opentelemetry:opentelemetry-exporter-zipkin - reports traces to Zipkin.

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

Use the management.zipkin.tracing.* configuration properties to configure reporting to Zipkin.

OpenTelemetry With Wavefront

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

Tracing with OpenTelemetry and reporting to Wavefront requires the following dependencies:

  • io.micrometer:micrometer-tracing-bridge-otel - bridges the Micrometer Observation API to OpenTelemetry.

  • io.micrometer:micrometer-tracing-reporter-wavefront - reports traces to Wavefront.

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

Use the management.wavefront.* configuration properties to configure reporting to Wavefront.

OpenTelemetry With OTLP

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

Tracing with OpenTelemetry and reporting using OTLP requires the following dependencies:

  • io.micrometer:micrometer-tracing-bridge-otel - bridges the Micrometer Observation API to OpenTelemetry.

  • io.opentelemetry:opentelemetry-exporter-otlp - reports traces to a collector that can accept OTLP.

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

Use the management.otlp.tracing.* configuration properties to configure reporting using OTLP.

OpenZipkin Brave With Zipkin

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

Tracing with OpenZipkin Brave and reporting to Zipkin requires the following dependencies:

  • io.micrometer:micrometer-tracing-bridge-brave - bridges the Micrometer Observation API to Brave.

  • io.zipkin.reporter2:zipkin-reporter-brave - reports traces to Zipkin.

如果您的项目未使用 Spring MVC 或 Spring WebFlux，则还需要 `io.zipkin.reporter2:zipkin-sender-urlconnection`依赖项。

If your project doesn’t use Spring MVC or Spring WebFlux, the io.zipkin.reporter2:zipkin-sender-urlconnection dependency is needed, too.

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

Use the management.zipkin.tracing.* configuration properties to configure reporting to Zipkin.

OpenZipkin Brave With Wavefront

使用 OpenZipkin Brave 并将报告提交给 Wavefront 需要以下依赖项：

Tracing with OpenZipkin Brave and reporting to Wavefront requires the following dependencies:

  • io.micrometer:micrometer-tracing-bridge-brave - bridges the Micrometer Observation API to Brave.

  • io.micrometer:micrometer-tracing-reporter-wavefront - reports traces to Wavefront.

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

Use the management.wavefront.* configuration properties to configure reporting to Wavefront.

Integration with Micrometer Observation

`TracingAwareMeterObservationHandler`将自动注册在 `ObservationRegistry`上，会为所有已完成的观测创建跨度。

A TracingAwareMeterObservationHandler is automatically registered on the ObservationRegistry, which creates spans for every completed observation.

Creating Custom Spans

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

You can create your own spans by starting an observation. For this, inject ObservationRegistry into your component:

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

This will create an observation named "some-operation" with the tag "some-tag=some-value".

如果您想创建一个跨度而不创建指标，则需要使用 Micrometer 中的 lower-level Tracer API。

If you want to create a span without creating a metric, you need to use the lower-level Tracer API from Micrometer.

Baggage

您可以使用 `Tracer`API 创建 Baggage：

You can create baggage with the Tracer API:

此示例创建了名为 baggage1`的 Baggage，其值为 `value1。如果您使用 W3C 传播，则 Baggage 会自动通过网络传播。如果您使用 B3 传播，则 Baggage 不会自动传播。要手动通过网络传播 Baggage，请使用 configprop:management.tracing.baggage.remote-fields[] 配置属性（这同样适用于 W3C）。对于以上示例，将此属性设置为 baggage1`将会创建一个 HTTP 头 `baggage1: value1。

This example creates baggage named baggage1 with the value value1. The baggage is automatically propagated over the network if you’re using W3C propagation. If you’re using B3 propagation, baggage is not automatically propagated. To manually propagate baggage over the network, use the configprop:management.tracing.baggage.remote-fields[] configuration property (this works for W3C, too). For the example above, setting this property to baggage1 results in an HTTP header baggage1: value1.

如果您想将 Baggage 传播到 MDC，请使用 configprop:management.tracing.baggage.correlation.fields[] 配置属性。对于以上示例，将此属性设置为 `baggage1`将会创建一个名为 `baggage1`的 MDC 条目。

If you want to propagate the baggage to the MDC, use the configprop:management.tracing.baggage.correlation.fields[] configuration property. For the example above, setting this property to baggage1 results in an MDC entry named baggage1.

Tests

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

Tracing components which are reporting data are not auto-configured when using @SpringBootTest. See the testing section for more details.