如何在MeterRegistry HealthIndicator中使用Gauge上报观测数据？

问题背景 #

我正在使用StatsD指标，尝试为自定义xxxHealthIndicator添加指标上报功能。现有实现代码如下：

public class xxxHealthIndicator implements HealthIndicator { 
    private final xxx xxx; 
    private final MeterRegistry meterRegistry; 

    @Autowired 
    public xxxHealthIndicator(xxx xxx, @Nullable MeterRegistry meterRegistry) { 
        this.xxx = xxx; 
        this.meterRegistry = meterRegistry; 
    } 

    @Override 
    public Health health() { 
        return A.getHealth(xxx.getHealth()); 
    } 
}

我计划在health()方法中添加指标上报代码，但对**"report data when observed"**的含义感到困惑，不确定是否需要监听状态变化。我的初步尝试代码如下：

@Override 
public Health health() { 
    if(meterRegistry!=null){ 
        Gauge gauge = Gauge 
            // 这里困惑"report data when observed"的含义，是否需要监听状态变化？
            .builder("xxxhealth", ????, ????) 
            .tags("status",xxx.getHealth.get("status")) 
            .register(meterRegistry); 
    } 
    return A.getHealth(xxx.getHealth()); 
}

参考Spring Boot 2.5.6文档，不需要额外添加HealthEndpoint，我整理了一个实现思路，但仍有疑问：

Gauge gauge = Gauge 
    .builder("xxxhealth", ????, this::getStatusCode ) 
    .tags("status",xxx.getHealth().get("status")) 
    .register(meterRegistry); 
} 

// xxx.getHealth()返回一个Map
private int getStatusCode(xxx health) { 
    String status = health.getHealth().get("status"); 
    if (Status.UP.equals(status)) { 
        return 3; 
    } 
    if (Status.OUT_OF_SERVICE.equals(status)) { 
        return 2; 
    } 
    if (Status.DOWN.equals(status)) { 
        return 1; 
    } 
    return 0; 
}

想请教：如何正确使用Gauge在观测时上报健康数据？

解决方案 #

核心概念澄清："report data when observed" #

这句话的意思是Gauge不需要主动监听状态变更，而是当监控系统（如StatsD）采集指标时，才实时计算并返回当前的健康状态值。Gauge是"按需计算"的指标，每次被观测时执行取值逻辑，无需你手动维护状态监听逻辑。

正确实现要点 #

1. 避免重复注册Gauge：不能在health()方法中每次调用都创建Gauge，这会导致重复注册同一指标，引发混乱。必须将Gauge的注册逻辑放到类的初始化阶段（比如构造方法或@PostConstruct方法），确保只执行一次。
2. 正确绑定数据源与取值逻辑：Gauge的第二个参数是被观测的对象，第三个参数是从该对象获取值的函数。这里直接绑定当前xxxHealthIndicator实例，通过方法引用实时获取健康状态码。
3. 标签处理注意事项：Micrometer的Gauge标签默认是静态的（注册时固定），如果需要标签随健康状态动态变化，有两种选择：
   • 放弃状态标签，用数值映射状态（如3=UP、2=OUT_OF_SERVICE等），监控系统可通过数值解析状态。
   • 额外注册Info类型指标专门上报状态字符串，Gauge仅负责上报数值。

修正后的完整代码 #

import io.micrometer.core.instrument.Gauge;
import io.micrometer.core.instrument.MeterRegistry;
import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.boot.actuate.health.Status;
import org.springframework.lang.Nullable;
import org.springframework.stereotype.Component;

import javax.annotation.PostConstruct;

@Component
public class xxxHealthIndicator implements HealthIndicator { 
    private final xxx xxx; 
    private final MeterRegistry meterRegistry; 

    @Autowired 
    public xxxHealthIndicator(xxx xxx, @Nullable MeterRegistry meterRegistry) { 
        this.xxx = xxx; 
        this.meterRegistry = meterRegistry; 
    } 

    @PostConstruct
    public void registerHealthGauge() {
        if (meterRegistry != null) {
            // 注册Gauge，每次观测时调用getStatusCode获取实时状态值
            Gauge.builder("xxx.health.status", this, this::getStatusCode)
                    .tag("component", "xxx-service") // 静态标签，标识服务组件
                    .register(meterRegistry);
        }
    }

    @Override 
    public Health health() { 
        return A.getHealth(xxx.getHealth()); 
    } 

    // 实时计算健康状态对应的数值
    private int getStatusCode(xxxHealthIndicator indicator) {
        String status = indicator.xxx.getHealth().get("status");
        if (Status.UP.name().equals(status)) {
            return 3;
        }
        if (Status.OUT_OF_SERVICE.name().equals(status)) {
            return 2;
        }
        if (Status.DOWN.name().equals(status)) {
            return 1;
        }
        return 0;
    }
}

额外说明 #

• 若你确实需要将状态作为动态标签，可通过MeterFilter实现，但逻辑相对复杂，一般不推荐。更简单的方式是同时上报两个指标：一个Gauge数值指标，一个Info文本指标。
• 确保xxx.getHealth()方法能实时返回最新的健康状态数据，这样Gauge每次采集时才能拿到准确值。

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