Tracing

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

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

Supported Tracers

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

Getting Started

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

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

在 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。

添加以下应用程序属性：

management:
  tracing:
    sampling:
      probability: 1.0

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

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

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

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

Hello World!

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

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

Logging Correlation IDs

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

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

如果您更喜欢为关联 ID 使用其他格式，则可以使用`configprop:logging.pattern.correlation[]`属性定义一个。例如，以下内容将为 Logback 提供关联 ID，采用 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[]`包含一个尾随空格，以便它默认与紧随其后的记录器名称分开。

Propagating Traces

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

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

Tracer Implementations

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

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

OpenTelemetry With Zipkin

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

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

  • io.opentelemetry:opentelemetry-exporter-zipkin - 向 Zipkin 报告跟踪。

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

OpenTelemetry With Wavefront

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

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

  • io.micrometer:micrometer-tracing-reporter-wavefront - 向 Wavefront 报告跟踪。

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

OpenTelemetry With 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 With Zipkin

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

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

  • io.zipkin.reporter2:zipkin-reporter-brave- 将报告提交给 Zipkin。

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

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

OpenZipkin Brave With Wavefront

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

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

  • io.micrometer:micrometer-tracing-reporter-wavefront - 向 Wavefront 报告跟踪。

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

Integration with Micrometer Observation

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

Creating Custom Spans

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

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

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

Baggage

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

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

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

Tests

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