跳到主要内容

可观测性

DeepSeek V3 中英对照 Observability

可观测性是指从外部观察运行中系统的内部状态的能力。它由三大支柱组成：日志记录、指标和追踪。

对于指标和追踪，Spring Boot 使用了 Micrometer Observation。要创建你自己的观测（这将生成指标和追踪），你可以注入一个 ObservationRegistry。

import io.micrometer.observation.Observation;
import io.micrometer.observation.ObservationRegistry;

import org.springframework.stereotype.Component;

@Component
public class MyCustomObservation {

    private final ObservationRegistry observationRegistry;

    public MyCustomObservation(ObservationRegistry observationRegistry) {
        this.observationRegistry = observationRegistry;
    }

    public void doSomething() {
        Observation.createNotStarted("doSomething", this.observationRegistry)
            .lowCardinalityKeyValue("locale", "en-US")
            .highCardinalityKeyValue("userId", "42")
            .observe(() -> {
                // Execute business logic here
            });
    }

}
java
备注

低基数的标签会被添加到指标和追踪中，而高基数的标签只会被添加到追踪中。

类型为 ObservationPredicate、GlobalObservationConvention、ObservationFilter 和 ObservationHandler 的 Bean 将会自动注册到 ObservationRegistry 中。此外，你还可以注册任意数量的 ObservationRegistryCustomizer Bean 来进一步配置注册表。

提示

JDBC 的可观测性可以通过一个单独的项目进行配置。Datasource Micrometer 项目提供了一个 Spring Boot 启动器，当调用 JDBC 操作时会自动创建观测。你可以在参考文档中了解更多信息。

提示

R2DBC 的可观测性已内置于 Spring Boot 中。要启用它，请将 io.r2dbc:r2dbc-proxy 依赖项添加到您的项目中。

上下文传播​

可观测性支持依赖于 Context Propagation library 来跨线程和响应式管道传递当前的观测信息。默认情况下，ThreadLocal 值不会在响应式操作符中自动恢复。这种行为可以通过 spring.reactor.context-propagation 属性来控制，设置为 auto 可以启用自动传播。

有关观测的更多详细信息，请参阅 Micrometer Observation 文档。

常用标签​

通用标签通常用于对操作环境进行维度下钻，例如主机、实例、区域、堆栈等。通用标签作为低基数标签应用于所有观测数据，并且可以配置，如下例所示：

management.observations.key-values.region=us-east-1
management.observations.key-values.stack=prod
properties

前面的示例为所有观测值分别添加了值为 us-east-1 和 prod 的 region 和 stack 标签。

防止观察​

如果你想阻止某些观测数据被上报，可以使用 management.observations.enable 属性：

management.observations.enable.denied.prefix=false
management.observations.enable.another.denied.prefix=false
properties

前面的示例将阻止所有名称以 denied.prefix 或 another.denied.prefix 开头的观察结果。

提示

如果你想阻止 Spring Security 报告观测信息，请将属性 management.observations.enable.spring.security 设置为 false。

如果你需要对观测的预防进行更精细的控制，可以注册类型为 ObservationPredicate 的 Bean。只有当所有 ObservationPredicate Bean 对该观测返回 true 时，观测才会被报告。

import io.micrometer.observation.Observation.Context;
import io.micrometer.observation.ObservationPredicate;

import org.springframework.stereotype.Component;

@Component
class MyObservationPredicate implements ObservationPredicate {

    @Override
    public boolean test(String name, Context context) {
        return !name.contains("denied");
    }

}
java

前面的示例将阻止所有名称包含 "denied" 的观测值。

OpenTelemetry 支持​

备注

在你的应用程序中支持 OpenTelemetry 有几种方式。你可以使用 OpenTelemetry Java Agent 或 OpenTelemetry Spring Boot Starter，这些由 OTel 社区支持；指标和追踪使用 OTel 库定义的语义约定。本文档描述的是由 Spring 团队正式支持的 OpenTelemetry，使用 Micrometer 和 OTLP 导出器；指标和追踪使用 Spring 项目文档中描述的语义约定，例如 Spring Framework。

Spring Boot 的 actuator 模块包含了对 OpenTelemetry 的基础支持。

它提供了一个类型为 OpenTelemetry 的 Bean，并且如果应用上下文中存在类型为 SdkTracerProvider、ContextPropagators、SdkLoggerProvider 或 SdkMeterProvider 的 Bean，它们会自动被注册。此外，它还提供了一个 Resource Bean。自动配置的 Resource 的属性可以通过 management.opentelemetry.resource-attributes 配置属性进行配置。如果你已经定义了自己的 Resource Bean，则不再适用此自动配置。

备注

Spring Boot 并未为 OpenTelemetry 的指标或日志提供自动配置。仅当与 Micrometer Tracing 一起使用时，OpenTelemetry 的追踪功能才会被自动配置。

接下来的章节将提供有关日志记录、指标和跟踪的更多详细信息。

Micrometer 观察注解支持​

要启用对 @Timed、@Counted、@MeterTag 和 @NewSpan 等指标和追踪注解的扫描，你需要将 management.observations.annotations.enabled 属性设置为 true。此功能由 Micrometer 直接支持。请参考 Micrometer 和 Micrometer Tracing 的参考文档。