订单支付成功率必须用gauge表示实时比率，而payment.total和payment.success等累计值需用counter；gauge须在应用启动时注册并用原子变量更新，不可重复注册或实时计算。
用 Counter 和 Gauge 区分“计数类”与“比率类”指标
订单支付成功率不是简单加一就能体现的，它本质是「成功数 ÷ 总数」的动态比值。直接用 Counter 只能记录分子和分母，但 Prometheus 本身不支持运行时计算除法（除非写 PromQL 聚合），所以得靠应用层维护一个可读取的实时比率值。Gauge 是唯一适合表达这种瞬时比值的类型，而 Counter 适合分别记录 payment.success 和 payment.total 这类单调递增量。
常见错误是试图用 Timer 或 DistributionSummary 替代成功率——它们适用于耗时或分布统计，跟成功率无直接关系；也有人误用 FunctionCounter 每次调用都重算，导致并发下精度丢失。
-
Counter用于累计：支付总次数、成功次数、失败次数，必须带明确tag如status=success、channel=wechat -
Gauge用于实时比率：用AtomicDouble或AtomicLong存储当前成功率，每次更新后调用gauge.set(value) - 不要在 HTTP handler 里实时算比率再注册新
Gauge——会重复注册，造成指标混乱
在 Spring Bean 生命周期中安全注册并更新 Gauge
Gauge 必须在应用启动时一次性注册，后续只更新其值；否则 Prometheus Scrape 时可能看到多个同名但不同实例的指标，导致 Grafana 查询异常。推荐在 @PostConstruct 或 MeterBinder 实现中完成注册，用线程安全的原子变量承载计算结果。
示例逻辑：
private final AtomicDouble successRate = new AtomicDouble(0.0);
private final Counter totalCounter;
private final Counter successCounter;
<p>@PostConstruct
public void initMetrics() {
// 注册两个 Counter
totalCounter = Counter.builder("payment.total").register(meterRegistry);
successCounter = Counter.builder("payment.success").register(meterRegistry);
// 注册 Gauge，绑定到 successRate 的 getAsDouble()
Gauge.builder("payment.success.rate", successRate, AtomicDouble::get)
.description("Real-time payment success rate")
.register(meterRegistry);
}</p><p>public void onPaymentResult(boolean isSuccess) {
totalCounter.increment();
if (isSuccess) successCounter.increment();
// 更新比率，注意避免除零
double rate = totalCounter.count() > 0
? successCounter.count() / totalCounter.count()
: 0.0;
successRate.set(rate);
}</p>
为什么不能只暴露 /actuator/prometheus 就完事？
单纯配置 management.endpoints.web.exposure.include=prometheus 只会让 Micrometer 把已注册的指标转成文本格式输出，但如果你没在业务代码里真正调用 Counter.increment() 或 Gauge.set()，Prometheus 拉到的就是空指标或默认零值——看着端点通了，实际没数据。
典型漏点：
- 埋点代码写在异步线程（如
@Async）里，但MeterRegistry默认不跨线程传播上下文，需显式传参或使用ThreadLocal绑定 - 支付回调接口被 Nginx 或网关拦截，根本没进 Spring Web 层，埋点自然失效——得在最外层（如 Filter 或 Gateway Route）补采
- 未给指标加
tag，比如漏掉.tag("env", "prod")，导致测试和生产数据混在一起，告警阈值失真
验证埋点是否生效的最快方式
别等 Grafana 配面板，直接 curl /actuator/prometheus 看原始输出：
$ curl -s http://localhost:8080/actuator/prometheus | grep payment
# HELP payment_total_total
# TYPE payment_total_total counter
payment_total_total{env="prod"} 127.0
# HELP payment_success_total
# TYPE payment_success_total counter
payment_success_total{env="prod"} 119.0
# HELP payment_success_rate
# TYPE payment_success_rate gauge
payment_success_rate{env="prod"} 0.937
如果只有 HELP 行没有数值行，说明指标注册了但没更新；如果有数值但长期不变，检查业务逻辑是否真走到埋点位置（加个 log.debug 最快）；如果 env 标签没出现，确认 tag() 调用在 register() 前。
真实环境里最容易被忽略的是：成功率这个 Gauge 值不会自动刷新，它只反映最后一次 set() 的快照——如果你的支付流量低频，这个数字可能卡住几分钟不动，但它本身没错，只是业务节奏决定的。
