对于最新稳定版本，请使用 Spring Boot 4.0.4！spring-doc.cadn.net.cn

可观测性

可观测性是指从外部观察运行中系统内部状态的能力。 它由三大支柱组成：日志（logging）、指标（metrics）和追踪（traces）。spring-doc.cadn.net.cn

对于指标和追踪，Spring Boot 使用 Micrometer Observation。 要创建您自己的观测（这将生成指标和追踪），您可以注入一个 ObservationRegistry。spring-doc.cadn.net.cn

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

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

import org.springframework.stereotype.Component

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

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

}
低基数标签将被添加到指标和追踪中，而高基数标签仅会被添加到追踪中。

类型为 ObservationPredicate、GlobalObservationConvention、ObservationFilter 和 ObservationHandler 的 Bean 将自动注册到 ObservationRegistry 上。 此外，您可以注册任意数量的 ObservationRegistryCustomizer Bean 以进一步配置该注册表。spring-doc.cadn.net.cn

可以使用一个独立的项目来配置 JDBC 的可观测性。 Datasource Micrometer 项目提供了一个 Spring Boot Starter，可在调用 JDBC 操作时自动创建观测数据。 更多详情请参阅参考文档。
R2DBC 的可观测性已内置于 Spring Boot 中。 要启用该功能，请将 io.r2dbc:r2dbc-proxy 依赖项添加到您的项目中。

上下文传播

可观测性支持依赖 上下文传播库 来在当前观察跨线程和响应式管道时进行转发。 默认情况下，ThreadLocal 值不会在响应式操作符中自动恢复。 此行为由 spring.reactor.context-propagation 属性控制，可将其设置为 auto 以启用自动传播。spring-doc.cadn.net.cn

如果您正在使用 @Async 方法或使用 AsyncTaskExecutor，则必须在执行器上注册 ContextPropagatingTaskDecorator，否则在切换线程时会丢失可观测性上下文。 这可以通过以下配置完成：spring-doc.cadn.net.cn

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.task.support.ContextPropagatingTaskDecorator;

@Configuration(proxyBeanMethods = false)
class ContextPropagationConfiguration {

	@Bean
	ContextPropagatingTaskDecorator contextPropagatingTaskDecorator() {
		return new ContextPropagatingTaskDecorator();
	}

}
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.core.task.support.ContextPropagatingTaskDecorator

@Configuration(proxyBeanMethods = false)
class ContextPropagationConfiguration {

	@Bean
	fun contextPropagatingTaskDecorator(): ContextPropagatingTaskDecorator {
		return ContextPropagatingTaskDecorator()
	}

}

有关观测（Observations）的更多详细信息，请参阅Micrometer Observation 文档。spring-doc.cadn.net.cn

常用标签

通用标签通常用于对运行环境进行维度下钻分析，例如主机（host）、实例（instance）、区域（region）、堆栈（stack）等。 通用标签会作为低基数标签应用于所有观测数据，并可进行配置，如下例所示：spring-doc.cadn.net.cn

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

前面的示例为所有观测（observations）分别添加了值为 region 的 stack 标签和值为 us-east-1 的 prod 标签。spring-doc.cadn.net.cn

防止观测

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

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

前面的示例将阻止所有名称以 denied.prefix 或 another.denied.prefix 开头的观测。spring-doc.cadn.net.cn

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

如果您需要对防止观测进行更精细的控制，可以注册类型为 ObservationPredicate 的 Bean。 仅当所有 ObservationPredicate Bean 对该观测返回 true 时，才会报告观测结果。spring-doc.cadn.net.cn

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

}
import io.micrometer.observation.Observation.Context
import io.micrometer.observation.ObservationPredicate
import org.springframework.stereotype.Component

@Component
class MyObservationPredicate : ObservationPredicate {

	override fun test(name: String, context: Context): Boolean {
		return !name.contains("denied")
	}

}

上述示例将阻止所有名称中包含“denied”的观测。spring-doc.cadn.net.cn

OpenTelemetry 支持

在您的应用程序中，有多种方式支持OpenTelemetry。 您可以使用由 OpenTelemetry（OTel）社区支持的OpenTelemetry Java Agent或OpenTelemetry Spring Boot Starter， 它们所使用的指标和追踪数据遵循 OTel 库定义的语义约定。 本文档介绍的是由 Spring 团队官方支持的 OpenTelemetry 方式，即使用 Micrometer 和 OTLP 导出器； 其指标和追踪数据遵循 Spring 项目文档（例如Spring Framework）中描述的语义约定。

Spring Boot 的 Actuator 模块包含对 OpenTelemetry 的基本支持。spring-doc.cadn.net.cn

它提供一个类型为 OpenTelemetry 的 Bean，如果应用上下文中存在类型为 SdkTracerProvider、ContextPropagators、SdkLoggerProvider 或 SdkMeterProvider 的 Bean，它们将自动注册。 此外，它还提供一个 Resource Bean。 自动配置的 Resource 的属性可以通过 management.opentelemetry.resource-attributes 配置属性进行配置。 自动配置的属性将与来自 OTEL_RESOURCE_ATTRIBUTES 和 OTEL_SERVICE_NAME 环境变量的属性合并，其中通过配置属性设置的属性优先级高于环境变量中的属性。spring-doc.cadn.net.cn

如果您定义了自己的 Resource bean，则情况将不再如此。spring-doc.cadn.net.cn

Spring Boot 不提供对 OpenTelemetry 指标（metrics）或日志记录（logging）的自动配置。 仅当与 Micrometer Tracing 一起使用时，才会自动配置 OpenTelemetry 追踪（tracing）。
OTEL_RESOURCE_ATTRIBUTES 环境变量由一组键值对组成。 例如：key1=value1,key2=value2,key3=spring%20boot。 所有属性值均被视为字符串，且任何超出 baggage-octet 范围的字符都必须进行百分号编码（percent-encoded）。

接下来的章节将提供更多关于日志、指标和追踪的详细信息。spring-doc.cadn.net.cn

Micrometer 观测注解支持

要启用对可观测性注解（如 @Observed、@Timed、@Counted、@MeterTag 和 @NewSpan）的扫描，请将 management.observations.annotations.enabled 属性设置为 true。 此外，还需要依赖 org.aspectj:aspectjweaver，它是 spring-boot-starter-aop 的一部分。 此功能由 Micrometer 直接支持。 请参阅 Micrometer、Micrometer Observation 和 Micrometer Tracing 参考文档。spring-doc.cadn.net.cn

当您注解已经通过字节码增强（例如，Spring Data 仓库或Spring MVC 控制器）的方法或类时，将会产生重复的观测数据。 在这种情况下，您可以选择使用配置属性或ObservationPredicate来禁用自动字节码增强，从而仅依赖您的注解；或者您也可以直接移除这些注解。