可观测性

可观测性是指从外部观察正在运行系统内部状态的能力。 它包含三大支柱：日志、指标和追踪。

对于指标和追踪，Spring Boot 使用 Micrometer Observation。 如需创建自定义 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
			});
	}

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

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

JDBC 可观测性可通过独立项目配置。 Datasource Micrometer 项目 提供了 Spring Boot starter，可在 JDBC 操作发生时自动创建 observation。 详细内容请参阅 参考文档。
R2DBC 可观测性已内置于 Spring Boot。 只需在项目中添加 io.r2dbc:r2dbc-proxy 依赖即可启用。

上下文传播

可观测性支持依赖 Context Propagation 库，用于在多线程和响应式管道间转发当前 observation。 默认情况下，ThreadLocal 的值不会自动在响应式操作符中恢复。 该行为可通过 spring.reactor.context-propagation 属性控制，设置为 auto 可启用自动传播。

更多 observation 细节请参阅 Micrometer Observation 文档。

公共标签

公共标签通常用于对运行环境进行维度下钻，如主机、实例、区域、堆栈等。 公共标签会作为低基数标签应用于所有 observation，可按如下方式配置：

  • Properties

  • YAML

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

上述示例为所有 observation 添加了 region 和 stack 标签，值分别为 us-east-1 和 prod。

阻止 Observation

如需阻止部分 observation 被上报，可使用 management.observations.enable 属性：

  • Properties

  • YAML

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 开头的 observation。

若需阻止 Spring Security 上报 observation，可将 management.observations.enable.spring.security 属性设为 false。

如需更细粒度控制，可注册类型为 ObservationPredicate 的 Bean。 仅当所有 ObservationPredicate Bean 对该 observation 返回 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");
	}

}

上述示例将阻止所有名称包含 "denied" 的 observation。

OpenTelemetry 支持

支持 OpenTelemetry 有多种方式。 可使用 OpenTelemetry Java Agent 或 OpenTelemetry Spring Boot Starter，这些由 OTel 社区维护；其指标和追踪遵循 OTel 库定义的语义约定。 本文档描述 Spring 团队官方支持的 OpenTelemetry 方案，基于 Micrometer 和 OTLP exporter；其指标和追踪遵循 Spring 项目文档（如 Spring Framework）中描述的语义约定。

Spring Boot 的 actuator 模块内置了对 OpenTelemetry 的基础支持。

它会提供类型为 OpenTelemetry 的 Bean，若应用上下文中存在 SdkTracerProvider、ContextPropagators、SdkLoggerProvider 或 SdkMeterProvider 类型的 Bean，会自动注册。 此外，还会提供 Resource Bean。 自动配置的 Resource 属性可通过 management.opentelemetry.resource-attributes 配置。 自动配置属性会与 OTEL_RESOURCE_ATTRIBUTES 和 OTEL_SERVICE_NAME 环境变量中的属性合并，配置属性优先生效。

如果你自定义了 Resource Bean，则不会再自动配置。

Spring Boot 不会为 OpenTelemetry 指标或日志提供自动配置。 仅当与 Micrometer Tracing 一起使用时，才会自动配置 OpenTelemetry tracing。
OTEL_RESOURCE_ATTRIBUTES 环境变量为键值对列表。 如：key1=value1,key2=value2,key3=spring%20boot。 所有属性值均视为字符串，超出 baggage-octet 范围的字符需百分号编码。

后续章节将详细介绍日志、指标和追踪。

Micrometer Observation 注解支持

如需启用对 @Observed、@Timed、@Counted、@MeterTag 和 @NewSpan 等可观测性注解的扫描，需将 management.observations.annotations.enabled 属性设为 true。 该特性由 Micrometer 直接支持。 详见 Micrometer、https://docs.micrometer.io/micrometer/reference/1.15/observation/components.html#micrometer-observation-annotations[Micrometer Observation] 及 Micrometer Tracing 参考文档。

若对已自动埋点（如 Spring Data 仓库 或 Spring MVC 控制器）的方法或类添加注解，会导致 observation 重复。 此时可通过 属性 或 ObservationPredicate 禁用自动埋点，仅依赖注解，或移除注解。