Spring Boot 3.4+ WebClient替代废弃Metrics Filter后指标uri异常问题

核心原因 #

Spring Boot 3.x 采用Micrometer Observability API替代了旧版的MetricsFilter，默认的客户端观测配置未正确提取请求URI路径，导致指标中uri标签显示为UNKNOWN。

解决方案步骤 #

1. 确保依赖齐全 #

确认pom.xml（或build.gradle）中包含以下依赖（若尚未添加）：

<!-- Spring Boot Actuator 用于暴露指标 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<!-- Micrometer Prometheus 注册表 -->
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
    <scope>runtime</scope>
</dependency>

2. 配置WebClient的观测规则 #

创建自定义的ClientRequestObservationConvention，确保正确提取请求URI路径，并注入到WebClient构建器中：

import io.micrometer.observation.ObservationRegistry;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.reactive.function.client.WebClient;
import io.micrometer.observation.web.reactive.client.DefaultClientRequestObservationConvention;
import io.micrometer.observation.web.reactive.client.ClientRequestObservationContext;
import java.net.URI;

@Configuration
public class WebClientConfig {

    @Bean
    public WebClient webClient(ObservationRegistry observationRegistry) {
        return WebClient.builder()
                // 绑定观测注册表
                .observationRegistry(observationRegistry)
                // 设置自定义观测规则
                .observationConvention(new CustomClientRequestObservationConvention())
                .build();
    }

    // 自定义观测规则，确保URI标签正确填充
    static class CustomClientRequestObservationConvention extends DefaultClientRequestObservationConvention {
        @Override
        protected String uri(ClientRequestObservationContext context) {
            URI requestUri = context.getRequest().getUrl();
            if (requestUri != null) {
                // 返回纯路径（可根据需求调整，比如保留部分路径或去掉查询参数）
                return requestUri.getPath();
            }
            // 兜底使用默认逻辑
            return super.uri(context);
        }
    }
}

3. 配置application.yml启用URI标签 #

在配置文件中开启WebClient请求的URI标签采集：

management:
  endpoints:
    web:
      exposure:
        include: prometheus # 暴露Prometheus端点
  metrics:
    web:
      client:
        request:
          tagging:
            uri:
              enabled: true # 启用URI标签采集

4. 规范WebClient请求写法 #

使用URI模板方式发送请求，便于观测系统识别统一的路径模板（避免每个带参数的请求都生成唯一URI标签）：

// 推荐写法：使用模板占位符
webClient.get()
        .uri("/api/users/{userId}", 1001)
        .retrieve()
        .bodyToMono(User.class);

// 不推荐：直接拼接带参数的URI字符串
// webClient.get().uri("/api/users/1001")...

验证结果 #

配置完成后，访问/actuator/prometheus端点，即可看到类似以下的正确指标：

http_client_requests_seconds{error="none",status="200",uri="/api/users/{userId}",quantile="0.9"} 0.012

内容的提问来源于stack exchange，提问作者donm