版本：7.0.2

本站内所有文档均为中英对照文档，点击中文可以显示英文。此提醒连续关闭5次后，将不再显示。

文档内容来源于 spring.io，由 springdoc.tech 翻译，版权归属于 SPRING.IO (Broadcom. Inc)。可供个人学习、研究，未经许可，不得进行转载或用于商业行为。

可观测性

DeepSeek V3 中英对照 Observability

Spring Security 与 Spring Observability 开箱即用，支持追踪功能；同时配置以收集指标也相当简单。

追踪

当存在 ObservationRegistry bean 时，Spring Security 会为以下操作创建追踪：

过滤器链
ReactiveAuthenticationManager，以及
ReactiveAuthorizationManager

启动集成

例如，考虑一个简单的Boot应用程序：

Java
Kotlin

@SpringBootApplication
public class MyApplication {
	@Bean
	public ReactiveUserDetailsService userDetailsService() {
		return new MapReactiveUserDetailsManager(
				User.withDefaultPasswordEncoder()
						.username("user")
						.password("password")
						.authorities("app")
						.build()
		);
	}

	@Bean
	ObservationRegistryCustomizer<ObservationRegistry> addTextHandler() {
		return (registry) -> registry.observationConfig().observationHandler(new ObservationTextPublisher());
	}

	public static void main(String[] args) {
		SpringApplication.run(ListenerSamplesApplication.class, args);
	}
}

@SpringBootApplication
class MyApplication {
	@Bean
	fun userDetailsService(): ReactiveUserDetailsService {
		MapReactiveUserDetailsManager(
				User.withDefaultPasswordEncoder()
						.username("user")
						.password("password")
						.authorities("app")
						.build()
		);
	}

	@Bean
	fun addTextHandler(): ObservationRegistryCustomizer<ObservationRegistry> {
		return registry: ObservationRegistry -> registry.observationConfig()
				.observationHandler(ObservationTextPublisher());
	}

	fun main(args: Array<String>) {
		runApplication<MyApplication>(*args)
	}
}

以及相应的请求：

?> http -a user:password :8080

将产生以下输出（为清晰起见，已添加缩进）：

START - name='http.server.requests', contextualName='null', error='null', lowCardinalityKeyValues=[], highCardinalityKeyValues=[], map=[class io.micrometer.tracing.handler.TracingObservationHandler$TracingContext='io.micrometer.tracing.handler.TracingObservationHandler$TracingContext@5dfdb78', class io.micrometer.core.instrument.LongTaskTimer$Sample='SampleImpl{duration(seconds)=0.00191856, duration(nanos)=1918560.0, startTimeNanos=101177265022745}', class io.micrometer.core.instrument.Timer$Sample='io.micrometer.core.instrument.Timer$Sample@121549e0']
	START - name='spring.security.http.chains', contextualName='spring.security.http.chains.before', error='null', lowCardinalityKeyValues=[chain.size='14', filter.section='before'], highCardinalityKeyValues=[request.line='/'], map=[class io.micrometer.tracing.handler.TracingObservationHandler$TracingContext='io.micrometer.tracing.handler.TracingObservationHandler$TracingContext@3932a48c', class io.micrometer.core.instrument.LongTaskTimer$Sample='SampleImpl{duration(seconds)=4.65777E-4, duration(nanos)=465777.0, startTimeNanos=101177276300777}', class io.micrometer.core.instrument.Timer$Sample='io.micrometer.core.instrument.Timer$Sample@562db70f']
	STOP - name='spring.security.http.chains', contextualName='spring.security.http.chains.before', error='null', lowCardinalityKeyValues=[chain.size='14', filter.section='before'], highCardinalityKeyValues=[request.line='/'], map=[class io.micrometer.tracing.handler.TracingObservationHandler$TracingContext='io.micrometer.tracing.handler.TracingObservationHandler$TracingContext@3932a48c', class io.micrometer.core.instrument.LongTaskTimer$Sample='SampleImpl{duration(seconds)=0.003733105, duration(nanos)=3733105.0, startTimeNanos=101177276300777}', class io.micrometer.core.instrument.Timer$Sample='io.micrometer.core.instrument.Timer$Sample@562db70f']
		START - name='spring.security.authentications', contextualName='null', error='null', lowCardinalityKeyValues=[authentication.failure.type='Optional', authentication.method='UserDetailsRepositoryReactiveAuthenticationManager', authentication.request.type='UsernamePasswordAuthenticationToken'], highCardinalityKeyValues=[], map=[class io.micrometer.tracing.handler.TracingObservationHandler$TracingContext='io.micrometer.tracing.handler.TracingObservationHandler$TracingContext@574ba6cd', class io.micrometer.core.instrument.LongTaskTimer$Sample='SampleImpl{duration(seconds)=3.21015E-4, duration(nanos)=321015.0, startTimeNanos=101177336038417}', class io.micrometer.core.instrument.Timer$Sample='io.micrometer.core.instrument.Timer$Sample@49202cc7']
		STOP - name='spring.security.authentications', contextualName='null', error='null', lowCardinalityKeyValues=[authentication.failure.type='Optional', authentication.method='UserDetailsRepositoryReactiveAuthenticationManager', authentication.request.type='UsernamePasswordAuthenticationToken', authentication.result.type='UsernamePasswordAuthenticationToken'], highCardinalityKeyValues=[], map=[class io.micrometer.tracing.handler.TracingObservationHandler$TracingContext='io.micrometer.tracing.handler.TracingObservationHandler$TracingContext@574ba6cd', class io.micrometer.core.instrument.LongTaskTimer$Sample='SampleImpl{duration(seconds)=0.37574992, duration(nanos)=3.7574992E8, startTimeNanos=101177336038417}', class io.micrometer.core.instrument.Timer$Sample='io.micrometer.core.instrument.Timer$Sample@49202cc7']
		START - name='spring.security.authorizations', contextualName='null', error='null', lowCardinalityKeyValues=[object.type='SecurityContextServerWebExchange'], highCardinalityKeyValues=[], map=[class io.micrometer.tracing.handler.TracingObservationHandler$TracingContext='io.micrometer.tracing.handler.TracingObservationHandler$TracingContext@6f837332', class io.micrometer.core.instrument.LongTaskTimer$Sample='SampleImpl{duration(seconds)=2.65687E-4, duration(nanos)=265687.0, startTimeNanos=101177777941381}', class io.micrometer.core.instrument.Timer$Sample='io.micrometer.core.instrument.Timer$Sample@7f5bc7cb']
		STOP - name='spring.security.authorizations', contextualName='null', error='null', lowCardinalityKeyValues=[authorization.decision='true', object.type='SecurityContextServerWebExchange'], highCardinalityKeyValues=[authentication.authorities='[app]', authorization.decision.details='AuthorizationDecision [granted=true]'], map=[class io.micrometer.tracing.handler.TracingObservationHandler$TracingContext='io.micrometer.tracing.handler.TracingObservationHandler$TracingContext@6f837332', class io.micrometer.core.instrument.LongTaskTimer$Sample='SampleImpl{duration(seconds)=0.039239047, duration(nanos)=3.9239047E7, startTimeNanos=101177777941381}', class io.micrometer.core.instrument.Timer$Sample='io.micrometer.core.instrument.Timer$Sample@7f5bc7cb']
		START - name='spring.security.http.secured.requests', contextualName='null', error='null', lowCardinalityKeyValues=[], highCardinalityKeyValues=[], map=[class io.micrometer.tracing.handler.TracingObservationHandler$TracingContext='io.micrometer.tracing.handler.TracingObservationHandler$TracingContext@2f33dfae', class io.micrometer.core.instrument.LongTaskTimer$Sample='SampleImpl{duration(seconds)=3.1775E-4, duration(nanos)=317750.0, startTimeNanos=101177821377592}', class io.micrometer.core.instrument.Timer$Sample='io.micrometer.core.instrument.Timer$Sample@63b0d28f']
		STOP - name='spring.security.http.secured.requests', contextualName='null', error='null', lowCardinalityKeyValues=[], highCardinalityKeyValues=[], map=[class io.micrometer.tracing.handler.TracingObservationHandler$TracingContext='io.micrometer.tracing.handler.TracingObservationHandler$TracingContext@2f33dfae', class io.micrometer.core.instrument.LongTaskTimer$Sample='SampleImpl{duration(seconds)=0.219901971, duration(nanos)=2.19901971E8, startTimeNanos=101177821377592}', class io.micrometer.core.instrument.Timer$Sample='io.micrometer.core.instrument.Timer$Sample@63b0d28f']
	START - name='spring.security.http.chains', contextualName='spring.security.http.chains.after', error='null', lowCardinalityKeyValues=[chain.size='14', filter.section='after'], highCardinalityKeyValues=[request.line='/'], map=[class io.micrometer.tracing.handler.TracingObservationHandler$TracingContext='io.micrometer.tracing.handler.TracingObservationHandler$TracingContext@40b25623', class io.micrometer.core.instrument.LongTaskTimer$Sample='SampleImpl{duration(seconds)=3.25118E-4, duration(nanos)=325118.0, startTimeNanos=101178044824275}', class io.micrometer.core.instrument.Timer$Sample='io.micrometer.core.instrument.Timer$Sample@3b6cec2']
	STOP - name='spring.security.http.chains', contextualName='spring.security.http.chains.after', error='null', lowCardinalityKeyValues=[chain.size='14', filter.section='after'], highCardinalityKeyValues=[request.line='/'], map=[class io.micrometer.tracing.handler.TracingObservationHandler$TracingContext='io.micrometer.tracing.handler.TracingObservationHandler$TracingContext@40b25623', class io.micrometer.core.instrument.LongTaskTimer$Sample='SampleImpl{duration(seconds)=0.001693146, duration(nanos)=1693146.0, startTimeNanos=101178044824275}', class io.micrometer.core.instrument.Timer$Sample='io.micrometer.core.instrument.Timer$Sample@3b6cec2']
STOP - name='http.server.requests', contextualName='null', error='null', lowCardinalityKeyValues=[], highCardinalityKeyValues=[], map=[class io.micrometer.tracing.handler.TracingObservationHandler$TracingContext='io.micrometer.tracing.handler.TracingObservationHandler$TracingContext@5dfdb78', class io.micrometer.core.instrument.LongTaskTimer$Sample='SampleImpl{duration(seconds)=0.784320641, duration(nanos)=7.84320641E8, startTimeNanos=101177265022745}', class io.micrometer.core.instrument.Timer$Sample='io.micrometer.core.instrument.Timer$Sample@121549e0']

手动配置

对于非Spring Boot应用程序，或者需要覆盖现有的Boot配置，您可以发布自己的ObservationRegistry，Spring Security仍会识别并使用它。

Java
Kotlin
Xml

@SpringBootApplication
public class MyApplication {
	@Bean
	public ReactiveUserDetailsService userDetailsService() {
		return new MapReactiveUserDetailsManager(
				User.withDefaultPasswordEncoder()
						.username("user")
						.password("password")
						.authorities("app")
						.build()
		);
	}

	@Bean
	ObservationRegistry observationRegistry() {
		ObservationRegistry registry = ObservationRegistry.create();
		registry.observationConfig().observationHandler(new ObservationTextPublisher());
		return registry;
	}

	public static void main(String[] args) {
		SpringApplication.run(ListenerSamplesApplication.class, args);
	}
}

@SpringBootApplication
class MyApplication {
	@Bean
	fun userDetailsService(): ReactiveUserDetailsService {
		MapReactiveUserDetailsManager(
				User.withDefaultPasswordEncoder()
						.username("user")
						.password("password")
						.authorities("app")
						.build()
		);
	}

	@Bean
	fun observationRegistry(): ObservationRegistry {
		ObservationRegistry registry = ObservationRegistry.create()
		registry.observationConfig().observationHandler(ObservationTextPublisher())
		return registry
	}

	fun main(args: Array<String>) {
		runApplication<MyApplication>(*args)
	}
}

<sec:http auto-config="true" observation-registry-ref="ref">
	<sec:intercept-url pattern="/**" access="authenticated"/>
</sec:http>

<!-- define and configure ObservationRegistry bean -->

禁用可观测性

如果你不希望启用任何Spring Security的观测功能，在Spring Boot应用中，你可以发布一个ObservationRegistry.NOOP类型的@Bean。不过，这可能会关闭不仅仅是Spring Security的观测功能。

相反，你可以发布一个如下所示的 SecurityObservationSettings：

Java
Kotlin

@Bean
SecurityObservationSettings noSpringSecurityObservations() {
	return SecurityObservationSettings.noObservations();
}

@Bean
fun noSpringSecurityObservations(): SecurityObservationSettings {
	return SecurityObservationSettings.noObservations()
}

然后 Spring Security 将不会把任何过滤器链、认证或授权包装到它们的 ObservationXXX 对应版本中。

提示

目前没有通过 XML 配置来禁用观测功能的机制。只需不设置 observation-registry-ref 属性即可。

你也可以仅针对安全观察的子集禁用安全功能。例如，SecurityObservationSettings bean 默认会排除过滤器链的观察。因此，你也可以这样做：

Java
Kotlin

@Bean
SecurityObservationSettings defaultSpringSecurityObservations() {
	return SecurityObservationSettings.withDefaults().build();
}

@Bean
fun defaultSpringSecurityObservations(): SecurityObservationSettings {
	return SecurityObservationSettings.withDefaults().build()
}

或者，您可以根据默认设置单独开启或关闭观测功能：

Java
Kotlin

@Bean
SecurityObservationSettings allSpringSecurityObservations() {
	return SecurityObservationSettings.withDefaults()
            .shouldObserveFilterChains(true).build();
}

@Bean
fun allSpringSecurityObservations(): SecurityObservationSettings {
    return SecurityObservabilityDefaults.builder()
            .shouldObserveFilterChains(true).build()
}

备注

为了向后兼容，除非发布了 SecurityObservationSettings，否则所有 Spring Security 观测都将被启用。

跟踪列表

Spring Security 会在每个请求中追踪以下跨度：

spring.security.http.requests - 一个包装整个过滤器链（包括请求）的跨度
spring.security.http.chains.before - 一个包装安全过滤器接收部分的跨度
spring.security.http.chains.after - 一个包装安全过滤器返回部分的跨度
spring.security.http.secured.requests - 一个包装当前已受保护应用程序请求的跨度
spring.security.http.unsecured.requests - 一个包装 Spring Security 未保护请求的跨度
spring.security.authentications - 一个包装身份验证尝试的跨度
spring.security.authorizations - 一个包装授权尝试的跨度

提示

spring.security.http.chains.before + spring.security.http.secured.requests + spring.security.http.chains.after = spring.security.http.requests
spring.security.http.chains.before + spring.security.http.chains.after = Spring Security 在请求处理中的部分

追踪​

启动集成​

手动配置​

禁用可观测性​

跟踪列表​

追踪

启动集成

手动配置

禁用可观测性

跟踪列表