可观测性

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

对于指标和追踪，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
			});
	}

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

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

JDBC 的可观测性可以使用单独的项目进行配置。 Datasource Micrometer 项目提供了一个 Spring Boot starter，它会在调用 JDBC 操作时自动创建观测。 在 参考文档中了解更多信息。
R2DBC 的可观测性已内置到 Spring Boot 中。 要启用它，请将 io.r2dbc:r2dbc-proxy 依赖项添加到你的项目中。

上下文传播

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

有关观测的更多详细信息，请参阅 Micrometer 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"

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

防止观测

如果你想阻止某些观测被报告，可以使用 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 开头的观测。

如果你想阻止 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");
	}

}

前面的示例将阻止所有名称包含 "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 指标或日志记录的自动配置。 OpenTelemetry 追踪仅在与 Micrometer Tracing 一起使用时才会自动配置。

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

Micrometer Observation 注解支持

要启用对可观测性注解的扫描，如 @Observed、@Timed、@Counted、@MeterTag 和 @NewSpan，你需要将 management.observations.annotations.enabled 属性设置为 true。 此功能由 Micrometer 直接支持。 请参阅 Micrometer、https://docs.micrometer.io/micrometer/reference/1.14/observation/components.html#micrometer-observation-annotations[Micrometer Observation] 和 Micrometer Tracing 参考文档。

当你注解已经经过检测的方法或类时（例如，Spring Data repositories 或 Spring MVC controllers），你将获得重复的观测。 在这种情况下，你可以使用 属性 或 ObservationPredicate 禁用自动检测并依赖你的注解，或者你可以删除你的注解。