如何实现自定义复合Meter并原生集成到Micrometer及Spring Boot Actuator？

我想要实现一种名为HeartbeatMeter的新型Meter，用于跟踪上游数据源的心跳存活状态。其接口定义如下：

private interface HeartbeatMeter {
    void beat(Instant timestamp);
}

该Meter需要暴露两个Gauge指标：

• {metric.name}.alive：若最后一次心跳记录超过超时时间则为0，否则为1；
• {metric.name}.timeout：心跳超时时间（单位：秒）。

我希望遵循Micrometer原生Meter的初始化方式，示例代码如下：

HeartbeatMeter myHeartbeat = HeartbeatMeter.builder("my.pipeline.heartbeat")
        .withTimeout(30)
        .tags(myTags)
        .register(meterRegistry);

myHeartbeat.beat(Instant.now());

注册逻辑要求：若不存在指定名称和标签的Meter则创建新实例并注册到MeterRegistry，否则返回已存在的实例。

当前builder的register方法实现如下：

public HeartbeatMeter register(MeterRegistry meterRegistry) {
    var heartbeatMeter = new HeartbeatMeter(this.timeoutSeconds);

    Gauge.builder(String.format("%s.active", this.name), heartbeatMeter.activeSupplier())
            .tags(this.tags)
            .register(meterRegistry);
    Gauge.builder(String.format("%s.timeout", this.name), heartbeatMeter.timeoutSupplier())
            .tags(this.tags)
            .register(meterRegistry);

    return heartbeatMeter;
}

该方法在Meter未注册时可正常工作，但当Gauge已存在于注册表中时会出现异常，无法正常运行。我想知道是否有便捷的方法实现自定义复合Meter并集成到Micrometer中（关注的是自定义复合Meter的通用实现方式，HeartbeatMeter仅作为示例）。

要实现幂等注册的自定义复合Meter，核心是利用Micrometer的MeterRegistry复用机制，通过唯一标识（名称+标签）判断实例是否已存在，避免重复创建指标。

1. 封装复合Meter的状态与指标供应商 #

先将复合指标共享的状态封装到实现类中，每个指标对应独立的Supplier，确保状态可被多个Gauge共享：

class DefaultHeartbeatMeter implements HeartbeatMeter {
    private final long timeoutSeconds;
    private volatile Instant lastBeat;

    public DefaultHeartbeatMeter(long timeoutSeconds) {
        this.timeoutSeconds = timeoutSeconds;
        this.lastBeat = Instant.now();
    }

    @Override
    public void beat(Instant timestamp) {
        this.lastBeat = timestamp;
    }

    public Supplier<Double> aliveSupplier() {
        return () -> {
            long elapsed = Duration.between(lastBeat, Instant.now()).getSeconds();
            return elapsed <= timeoutSeconds ? 1.0 : 0.0;
        };
    }

    public Supplier<Long> timeoutSupplier() {
        return () -> timeoutSeconds;
    }
}

2. 基于Meter.Id实现幂等注册 #

Micrometer中每个Meter的唯一标识是Meter.Id（由名称、标签、类型等组成）。我们可以为复合Meter创建一个"虚拟"的Meter.Id作为标识，借助MeterRegistry.getOrCreateMeter实现实例复用：

修改Builder的register方法如下：

public HeartbeatMeter register(MeterRegistry meterRegistry) {
    // 为复合Meter创建唯一标识的Meter.Id
    Meter.Id meterId = new Meter.Id(
            this.name + ".heartbeat",
            Tags.of(this.tags),
            null,
            "heartbeat_meter",
            Meter.Type.GAUGE // 类型仅作标识用，不影响实际指标
    );

    // 幂等获取/创建实例：存在则返回，不存在则创建并注册指标
    return meterRegistry.getOrCreateMeter(meterId, () -> {
        DefaultHeartbeatMeter meter = new DefaultHeartbeatMeter(this.timeoutSeconds);
        
        // 注册两个Gauge，开启strongReference避免实例被GC回收
        Gauge.builder(this.name + ".alive", meter.aliveSupplier())
                .tags(this.tags)
                .strongReference(true)
                .register(meterRegistry);
        
        Gauge.builder(this.name + ".timeout", meter.timeoutSupplier())
                .tags(this.tags)
                .strongReference(true)
                .register(meterRegistry);
        
        return meter;
    }, DefaultHeartbeatMeter.class);
}

3. 通用实现思路总结 #

所有自定义复合Meter都可以遵循以下步骤：

• 状态封装：将复合指标共享的状态集中到一个实现类，每个指标对应一个Supplier；
• 唯一标识：为复合Meter定义专属的Meter.Id，用于在注册表中识别实例；
• 幂等注册：通过MeterRegistry.getOrCreateMeter确保同一标识下仅创建一次实例；
• 指标绑定：在实例创建阶段一次性注册所有关联指标，确保它们绑定到同一个状态实例。

这种方式既符合Micrometer原生API的使用习惯，又能避免重复注册指标的问题。

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