Java 后端 / 系统课时
采集 Micrometer 指标
采集 Micrometer 指标
Micrometer 把业务代码中的计数、耗时和当前状态转换为统一指标。本课将接入指标注册表,编写 Counter、Timer、Gauge 主示例,并通过 Actuator 与 Prometheus 格式验证采集结果。
学习目标
- 根据业务语义选择 Counter、Timer 和 Gauge。
- 使用
MeterRegistry注册低基数、可聚合的自定义指标。 - 通过
/actuator/metrics和/actuator/prometheus验证指标。
选择正确的指标类型
Micrometer 的核心是 MeterRegistry。业务代码向注册表记录数据,Actuator 可以用于诊断查询,监控注册表则把同一批指标转换为 Prometheus 等后端需要的格式。
| 类型 | 记录内容 | 典型场景 |
|---|---|---|
Counter |
只增不减的累计次数 | 创建订单数、失败次数 |
Timer |
调用次数与耗时分布 | 接口处理时间、外部调用延迟 |
Gauge |
某一时刻的当前值 | 队列长度、处理中任务数 |
Timer 已经包含调用次数,不要只为统计同一事件次数再复制一个 Counter。Gauge 适合会增会减的状态值,而且被观测对象必须保持有效引用。标签应使用渠道、结果、区域等有限集合,禁止把订单号、用户 ID 或请求路径原文作为标签。

接入注册表并编写指标
独立运行本示例需要 Actuator 与 Prometheus 注册表。Spring Boot 会自动创建 MeterRegistry,并把 JVM、HTTP、线程池等内置指标一并注册。
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-registry-prometheus</artifactId>
</dependency>
</dependencies>开放诊断和抓取端点,并给所有指标增加稳定的应用标签。直方图会增加时间序列数量,只应为确实需要分位数或延迟分布的 Timer 开启。
management:
endpoints:
web:
exposure:
include: health,metrics,prometheus
metrics:
tags:
application: order-service
distribution:
percentiles-histogram:
orders.processing: true将下面代码保存为 MetricsDemoApplication.java。一次创建请求会增加订单计数,用 Timer 记录处理耗时,并在处理期间调整待处理订单 Gauge。
package com.example.metrics;
import java.time.Duration;
import java.util.Map;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.concurrent.locks.LockSupport;
import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.Gauge;
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.stereotype.Component;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
@SpringBootApplication
public class MetricsDemoApplication {
public static void main(String[] args) {
SpringApplication.run(MetricsDemoApplication.class, args);
}
}
@RestController
class OrderController {
private final OrderMetrics metrics;
OrderController(OrderMetrics metrics) {
this.metrics = metrics;
}
@PostMapping("/orders")
Map<String, String> createOrder() {
return Map.of("status", metrics.recordCreation());
}
}
@Component
class OrderMetrics {
private final Counter createdCounter;
private final Timer processingTimer;
private final AtomicInteger pendingOrders = new AtomicInteger();
OrderMetrics(MeterRegistry registry) {
this.createdCounter = Counter.builder("orders.created")
.description("Accepted order count")
.tag("channel", "api")
.register(registry);
this.processingTimer = Timer.builder("orders.processing")
.description("Order processing latency")
.publishPercentileHistogram()
.register(registry);
Gauge.builder("orders.pending", pendingOrders, AtomicInteger::get)
.description("Orders currently being processed")
.register(registry);
}
String recordCreation() {
pendingOrders.incrementAndGet();
try {
return processingTimer.record(() -> {
// 模拟业务耗时;真实项目中替换为订单保存与事件发布。
LockSupport.parkNanos(Duration.ofMillis(80).toNanos());
createdCounter.increment();
return "accepted";
});
} finally {
pendingOrders.decrementAndGet();
}
}
}预期输出
Started MetricsDemoApplication in <TIME> seconds<TIME> 由机器性能决定。应用启动后,Spring 会自动把三个自定义 Meter 注册到同一个注册表。
调用接口并验证采集结果
先创建一个订单,再查询 Counter 与 Gauge。指标值取决于调用次数和查询时刻,因此使用动态占位符表示;首次调用后 <COUNT> 通常为 1.0,请求结束后 <CURRENT_PENDING> 通常为 0.0。
curl -s -X POST http://localhost:8080/orders
curl -s "http://localhost:8080/actuator/metrics/orders.created?tag=channel:api"
curl -s http://localhost:8080/actuator/metrics/orders.pending预期输出
{"status":"accepted"}
{"name":"orders.created","measurements":[{"statistic":"COUNT","value":<COUNT>}],...}
{"name":"orders.pending","measurements":[{"statistic":"VALUE","value":<CURRENT_PENDING>}],...}再检查 Prometheus 暴露格式。标签顺序和浮点值可能不同,但应能找到计数、Timer 调用次数和当前待处理数。
curl -s http://localhost:8080/actuator/prometheus | grep -E '^orders_(created_total|processing_seconds_count|pending)'预期输出
orders_created_total{application="order-service",channel="api"} <COUNT>
orders_processing_seconds_count{application="order-service"} <COUNT>
orders_pending{application="order-service"} <CURRENT_PENDING>若 /actuator/metrics 找不到名称,先确认代码路径至少执行过一次;若 /actuator/prometheus 为 404,检查 Prometheus 注册表依赖和端点暴露白名单。出现大量时间序列时,应优先检查标签中是否混入了高基数值。