Spring Framework 可观测性支持深度解析-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00172/article/details/148324377

Spring Framework 可观测性支持深度解析

spring-framework 项目地址: https://gitcode.com/gh_mirrors/spr/spring-framework

1. 可观测性概述

在现代分布式系统中，可观测性(Observability)已成为系统监控和故障排查的关键能力。Spring Framework通过集成Micrometer库，为应用程序提供了全面的可观测性支持。

可观测性主要包含三个核心维度：

指标(Metrics)：用于收集应用程序运行时行为的统计数据，如计时器、计数器和仪表等
追踪(Traces)：提供跨越应用边界的全系统视图，可追踪特定用户请求的完整调用链
日志(Logs)：记录系统运行过程中的详细事件信息

Spring Framework通过在自身代码库的关键位置添加观测点，当配置了ObservationRegistry时，会自动发布观测数据。

2. Spring Framework支持的观测类型

Spring Framework为以下功能提供了开箱即用的观测支持：

| 观测名称 | 描述 | |---------|------| | http.client.requests | HTTP客户端请求耗时 | | http.server.requests | HTTP服务器请求处理时间 | | jms.message.publish | JMS消息发送耗时 | | jms.message.process | JMS消息处理时间 | | tasks.scheduled.execution | @Scheduled任务执行时间 |

这些观测名称遵循Micrometer的官方命名规范，但会根据监控系统后端(如Prometheus、Atlas等)的偏好自动转换格式。

3. Micrometer观测核心概念

3.1 基本组件

Observation：记录应用程序中发生的事件，由ObservationHandler实现处理生成指标或追踪
ObservationContext：保存观测相关上下文信息，如HTTP请求、响应、异常等
KeyValues：观测的元数据，如HTTP方法、状态码等
ObservationConvention：定义如何从上下文中提取元数据

3.2 元数据分类

低基数(Low Cardinality)：值范围有限且边界明确的元数据(如HTTP方法)，适合用于指标
高基数(High Cardinality)：值范围无界的元数据(如请求URI)，仅用于追踪

4. 观测配置

4.1 全局配置

通过ObservationRegistry#observationConfig()进行全局配置，每个组件需要：

设置ObservationRegistry(未设置则不会记录观测)
提供自定义ObservationConvention来修改默认观测名称和元数据

4.2 自定义观测约定

以Spring MVC的HTTP服务器观测为例，可以通过以下方式自定义：

// 扩展默认约定
public class ExtendedServerRequestObservationConvention 
    extends DefaultServerRequestObservationConvention {
    // 自定义实现...
}

// 或完全实现约定接口
public class CustomServerRequestObservationConvention 
    implements ServerRequestObservationConvention {
    // 完整实现...
}

4.3 使用观测过滤器

观测过滤器(ObservationFilter)可用于后处理观测数据：

public class ServerRequestObservationFilter implements ObservationFilter {
    @Override
    public Observation.Context transform(Observation.Context context) {
        // 添加或修改键值
        return context;
    }
}

5. 定时任务观测

@Scheduled任务执行时会创建观测，需在ScheduledTaskRegistrar上配置ObservationRegistry：

@Configuration
public class ObservationSchedulingConfigurer implements SchedulingConfigurer {
    private final ObservationRegistry observationRegistry;
    
    @Override
    public void configureTasks(ScheduledTaskRegistrar taskRegistrar) {
        taskRegistrar.setObservationRegistry(observationRegistry);
    }
}

默认收集的元数据包括：

code.function：被调度执行的Java方法名
code.namespace：包含调度方法的类全名
error：执行过程中抛出的异常类名
outcome：方法执行结果(SUCCESS/ERROR/UNKNOWN)

6. JMS消息观测

需添加io.micrometer:micrometer-jakarta9依赖，支持两种观测：

消息发布(jms.message.publish)：测量消息发送时间
消息处理(jms.message.process)：测量消息处理时间

6.1 公共元数据

低基数键：

error：异常类名
messaging.destination.temporary：是否为临时目的地
messaging.operation：操作类型(publish/process)

高基数键：

messaging.message.conversation_id：消息关联ID
messaging.destination.name：目的地名称
messaging.message.id：消息ID

6.2 消息发布配置

在JmsTemplate上配置ObservationRegistry：

@Bean
public JmsTemplate jmsTemplate(ObservationRegistry registry) {
    JmsTemplate template = new JmsTemplate();
    template.setObservationRegistry(registry);
    return template;
}

6.3 消息处理配置

对于@JmsListener，需在容器工厂配置：

@Configuration
public class JmsConfiguration {
    @Bean
    public JmsListenerContainerFactory<?> jmsListenerContainerFactory(
            ObservationRegistry registry) {
        DefaultJmsListenerContainerFactory factory = new DefaultJmsListenerContainerFactory();
        factory.setObservationRegistry(registry);
        return factory;
    }
}

7. HTTP服务器观测

7.1 Servlet应用

需配置ServerHttpObservationFilter：

@Bean
public FilterRegistrationBean<ServerHttpObservationFilter> observationFilter() {
    FilterRegistrationBean<ServerHttpObservationFilter> registration = new FilterRegistrationBean<>();
    registration.setFilter(new ServerHttpObservationFilter());
    return registration;
}

默认元数据：

低基数：method, status, uri, error, outcome
高基数：http.url

7.2 响应式应用

需在WebHttpHandlerBuilder上配置：

@Bean
public HttpHandler httpHandler(ObservationRegistry registry) {
    return WebHttpHandlerBuilder
            .webHandler(routerFunction.toWebHandler())
            .observationRegistry(registry)
            .build();
}

8. HTTP客户端观测

8.1 RestTemplate

需配置ObservationRegistry：

@Bean
public RestTemplate restTemplate(ObservationRegistry registry) {
    RestTemplate template = new RestTemplate();
    template.setObservationRegistry(registry);
    return template;
}

8.2 RestClient

需在构建器上配置：

@Bean
public RestClient restClient(ObservationRegistry registry) {
    return RestClient.builder()
            .observationRegistry(registry)
            .build();
}

默认元数据：