可觀測性

可觀測性是指從外部觀察執行中系統的內部狀態的能力。它包括三個核心要素：日誌、指標和追蹤。

對於指標和追蹤，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 exporter；其指標和追蹤使用了 Spring 專案文件（例如 Spring Framework）中描述的語義規範。

Spring Boot 的 actuator 模組包含了對 OpenTelemetry 的基本支援。

它提供了一個 OpenTelemetry 型別的 Bean，並且如果在應用上下文中存在 SdkTracerProvider、ContextPropagators、SdkLoggerProvider 或 SdkMeterProvider 型別的 Bean，它們將自動註冊。此外，它還提供一個 Resource Bean。自動配置的 Resource 的屬性可以透過 management.opentelemetry.resource-attributes 配置屬性進行配置。如果你已經定義了自己的 Resource Bean，則不會自動配置 Resource。

Spring Boot 不為 OpenTelemetry 指標或日誌提供自動配置。OpenTelemetry 追蹤只有與 Micrometer Tracing 一起使用時才會自動配置。

下一節將提供關於日誌、指標和追蹤的更多詳細資訊。

Micrometer Observation 註解支援

要啟用對 @Observed、@Timed、@Counted、@MeterTag 和 @NewSpan 等可觀測性註解的掃描，你需要將 management.observations.annotations.enabled 屬性設定為 true。此功能由 Micrometer 直接支援。請參閱 Micrometer、Micrometer Observation 和 Micrometer Tracing 的參考文件。

當你註解已被 instrumented 的方法或類（例如 Spring Data 倉庫或 Spring MVC 控制器）時，你會得到重複的觀測。在這種情況下，你可以選擇使用 屬性 或 ObservationPredicate 停用自動 instrumented 並依賴你的註解，或者你可以移除你的註解。