可观察性

可观测性是指从外部观察运行系统内部状态的能力。它包括三大支柱：Logging、度量和痕迹。spring-doc.cadn.net.cn

对于度量和迹量，Spring Boot 使用微米观测。为了创建自己的观测值（这将导致度量和追踪），你可以注入一个ObservationRegistry.spring-doc.cadn.net.cn

Javaspring-doc.cadn.net.cn
Kotlinspring-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
			}
	}

}

低基数标签将被添加到度量和跟踪中，而高基数标签只会添加到跟踪中。

类型的豆子观察谓词,全球观察大会,观察Filter和观察处理器将自动注册ObservationRegistry. 你也可以注册任意数量的观察登记定制器Beans 以进一步配置注册表。spring-doc.cadn.net.cn

JDBC 的可观测性可以通过单独的项目进行配置。 Datasource Micrometer 项目提供了一个 Spring Boot Starters，当调用 JDBC作时自动生成观测值。可以阅读参考文献中的更多信息。

R2DBC 的可观测性内置于 Spring Boot 中。要启用它，添加io.r2dbc：r2dbc-proxy对项目的依赖。

上下文传播

可观察性支持依赖上下文传播库，用于将当前观察数据转发到线程和响应式流水线之间。默认情况下，ThreadLocal在响应式运算符中，值不会自动恢复。这种行为通过spring.reactor.context-propagation属性，可以设置为自动以实现自动传播。spring-doc.cadn.net.cn

如果你正在与@Async方法或使用异步任务执行器你必须注册ContextPropatingTaskDecorator在执行程序中，否则切换线程时可观测上下文会丢失。这可以通过以下配置实现：spring-doc.cadn.net.cn

Javaspring-doc.cadn.net.cn
Kotlinspring-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()
	}

}

有关观测的更多细节，请参阅Micrometer Observation文档。spring-doc.cadn.net.cn

常见标签

常见标签通常用于对作环境进行维度下降，如主机、实例、区域、堆栈等。所有观测都以低基数标签的形式应用通用标签，并且可以配置，如下示例所示：spring-doc.cadn.net.cn

Propertiesspring-doc.cadn.net.cn
YAMLspring-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"

前述例子补充地区和叠所有值为的观测值的标签美国东1号和刺分别。spring-doc.cadn.net.cn

防止观测

如果你想防止某些观测被报告，可以使用management.observations.enable性能：spring-doc.cadn.net.cn

Propertiesspring-doc.cadn.net.cn
YAMLspring-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.前缀或另一个.denied.前缀.spring-doc.cadn.net.cn

如果你想阻止Spring Security报告观测值，就设置属性管理。观察。使得能。春。安全自false.

如果你需要更好地控制观察的预防，可以登记类型的豆子观察谓词. 只有当所有观察谓词豆子回归true感谢你的观察。spring-doc.cadn.net.cn

Javaspring-doc.cadn.net.cn
Kotlinspring-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")
	}

}

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

支持微尺观测注释

以实现可观测性注释的扫描，如@Observed,@Timed,@Counted,@MeterTag和@NewSpan，你需要设置管理。观察。注释.启用属性到true. 该功能由Micrometer直接支持。请参阅《Micrometer》、《Micrometer Observation》和《Micrometer Treciation》参考文档。spring-doc.cadn.net.cn

当你注释已经被安装好工具的方法或类（例如，Spring Data 仓库或 Spring MVC 控制器）时，你会得到重复的观测值。在这种情况下，你可以用属性禁用自动仪器，或者观察谓词并且依赖你的注释，或者你也可以删除你的注释。

OpenTelemetry 支持

在您的应用中支持OpenTelemetry有多种方式。你可以使用 OpenTelemetry Java Agent 或 OpenTelemetry Spring Boot Starter，这些都得到了OTel社区的支持;度量和痕迹使用了 OTel 库定义的语义约定。本文档描述了 OpenTelemetry 由 Spring 团队官方支持，使用 Micrometer 和 OTLP 导出器; 度量和痕迹使用了 Spring 项目文档中描述的语义惯例，如 Spring Framework。

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

它提供了一种类型的“豆子”开放遥测，如果存在的豆子类型SdkTracerProvider,上下文传播器,SdkLoggerProvider或SdkMeterProvider在应用环境中，它们会自动注册。此外，它还提供了资源豆。自动配置的属性资源可以通过管理.opentelemetry.resource-attributes配置属性。自动配置的属性将与OTEL_RESOURCE_ATTRIBUTES和OTEL_SERVICE_NAME环境变量，通过配置属性配置的属性优先于环境变量中的属性。spring-doc.cadn.net.cn

如果你已经定义了自己的资源Bean，这种情况将不再发生。spring-doc.cadn.net.cn

Spring Boot 不支持自动导出 OpenTelemetry 的指标或日志。导出OpenTelemetry追踪只有在与Micrometer Tracing一起使用时才会自动配置。

环境变量

Spring Boot 支持以下环境变量来配置 OpenTelemetry 资源：spring-doc.cadn.net.cn

这OTEL_RESOURCE_ATTRIBUTES环境变量由一个键值对的列表组成。例如：key1=value1，key2=value2，key3=spring%20boot. 所有属性值都被视为字符串，任何超出包包八位元组范围的字符必须进行百分比编码。

Micrometer 还支持以下环境变量，用于配置通过 OTLP 导出的度量：spring-doc.cadn.net.cn

OpenTelemetry 文档中描述的其他环境变量不被支持。spring-doc.cadn.net.cn

如果你想让OpenTelemetry SDK指定的所有环境变量都有效，你必须自己提供开放遥测豆。spring-doc.cadn.net.cn

这样做会关闭 Spring Boot 的 OpenTelemetry 自动配置，并可能破坏内置的可观测性功能。

首先，添加一个依赖io.opentelemetry：opentelemetry-sdk-extension-autoconfigure获取OpenTelemetry的零代码SDK自动配置模块，然后添加以下配置：spring-doc.cadn.net.cn

import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
class AutoConfiguredOpenTelemetrySdkConfiguration {

	@Bean
	OpenTelemetry autoConfiguredOpenTelemetrySdk() {
		return AutoConfiguredOpenTelemetrySdk.initialize().getOpenTelemetrySdk();
	}

}

Logging

这OpenTelemetryLoggingAutoConfiguration配置 OpenTelemetry 的SdkLoggerProvider. 通过OTLP导出日志支持通过OtlpLoggingAutoConfiguration该技术支持通过HTTP或gRPC导出OTLP日志。spring-doc.cadn.net.cn

然而，虽然存在SdkLoggerProvider豆子，Spring Boot 不支持将日志桥接到这个豆子。这可以通过第三方日志桥接实现，详见“使用OpenTelemetry日志”部分。spring-doc.cadn.net.cn

指标

Spring组合中的指标选择为Micrometer，这意味着指标不会通过OpenTelemetry收集和导出SdkMeterProvider. Spring靴不提供SdkMeterProvider豆。spring-doc.cadn.net.cn

然而，微米度量可以通过OTLP导出到任何支持OpenTelemetry的后端，使用以下方式OtlpMeterRegistry如OTLP的度量部分所述。spring-doc.cadn.net.cn

Micrometer的OTLP注册表不使用资源豆子，但设置OTEL_RESOURCE_ATTRIBUTES,OTEL_SERVICE_NAME或管理.opentelemetry.resource-attributes工程。

通过OpenTelemetry API和SDK获取度量

如果你或你包含的依赖系统，可以使用OpenTelemetry。MeterProvider这些指标不会导出。spring-doc.cadn.net.cn

我们强烈建议您向Micrometer报告您的指标。如果你包含的依赖是用OpenTelemetry的MeterProvider你可以在应用中包含此配置以配置MeterProvider豆子，然后你必须把它接入你的依赖系统：spring-doc.cadn.net.cn

import java.time.Duration;

import io.opentelemetry.exporter.otlp.http.metrics.OtlpHttpMetricExporter;
import io.opentelemetry.sdk.metrics.SdkMeterProvider;
import io.opentelemetry.sdk.metrics.export.MetricExporter;
import io.opentelemetry.sdk.metrics.export.MetricReader;
import io.opentelemetry.sdk.metrics.export.PeriodicMetricReader;
import io.opentelemetry.sdk.resources.Resource;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
class OpenTelemetryMetricsConfiguration {

	@Bean
	OtlpHttpMetricExporter metricExporter() {
		String endpoint = "http://localhost:4318/v1/metrics";
		return OtlpHttpMetricExporter.builder().setEndpoint(endpoint).build();
	}

	@Bean
	PeriodicMetricReader metricReader(MetricExporter exporter) {
		Duration interval = Duration.ofMinutes(1);
		return PeriodicMetricReader.builder(exporter).setInterval(interval).build();
	}

	@Bean
	SdkMeterProvider meterProvider(Resource resource, MetricReader metricReader) {
		return SdkMeterProvider.builder().registerMetricReader(metricReader).setResource(resource).build();
	}

}

该配置还支持通过 HTTP 的 OTLP 导出指标。spring-doc.cadn.net.cn

描图

如果使用微米追踪，则OpenTelemetryTracingAutoConfiguration配置 OpenTelemetry 的SdkTracerProvider. 通过OTLP导出跟踪可以通过以下方式实现OtlpTracingAutoConfiguration支持通过HTTP或gRPC通过OTLP导出轨迹。spring-doc.cadn.net.cn

我们强烈建议使用Micrometer Observation或Tracing API，而不是直接使用OpenTelemetry API。spring-doc.cadn.net.cn