Java 应用接入 Prometheus 监控(Spring Boot 实战)
Spring Boot 接入 Prometheus:Micrometer + Actuator 暴露 /actuator/prometheus、JVM 默认指标解读、Counter/Gauge/Timer 自定义埋点与生产配置要点。
Spring Boot 接入 Prometheus 的常用路径是 Micrometer(指标门面)+ Actuator(端点暴露)。JVM 和 HTTP 指标可由 Spring Boot 自动配置,指标能否被抓取还取决于端点配置与网络。
第一步:依赖与配置
示例使用 Java 21、Spring Boot 3.5.16 和由 Spring Boot 管理的 Micrometer 1.15.12。把以下内容保存为 pom.xml:
<project xmlns="http://maven.apache.org/POM/4.0.0">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.5.16</version>
<relativePath/>
</parent>
<groupId>example</groupId>
<artifactId>checkout-metrics</artifactId>
<version>1.0.0</version>
<properties><java.version>21</java.version></properties>
<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>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
将以下配置保存为 src/main/resources/application.properties。业务端口与管理端口均监听回环地址,适用于本机演示:
server.address=127.0.0.1
server.port=8080
management.server.address=127.0.0.1
management.server.port=9091
management.endpoints.web.exposure.include=health,prometheus
加入下方示例代码并运行 mvn spring-boot:run 后,可在同一网络命名空间访问 http://127.0.0.1:9091/actuator/prometheus。要将指标送入观测云,可在 DataKit Prom 采集器的 urls 中配置采集器可达的受控端点。先核对一项 JVM Gauge 和一个业务 Counter 的名称、标签与值,再用于图表和检测规则。Spring Boot Actuator 端点
默认白送的指标
依赖和端点配置就绪后,检查 JVM 与应用指标:
jvm_memory_used_bytes(堆/非堆)、jvm_threads_live_threads(存活线程数)、process_cpu_usage(进程近期 CPU 使用率);jvm_gc_pause_seconds_count与jvm_gc_pause_seconds_sum是 GC 停顿次数与累计时长,是否有样本取决于 JVM 和实际 GC 事件;- Spring MVC 请求的
http.server.requests在 Prometheus 中可见为http_server_requests_seconds_count、_sum等序列。先访问业务路由让指标产生样本。默认请求 Timer 不必然输出_bucket,不能仅凭自动埋点就查询 HTTP P99。Spring Boot HTTP 与 JVM 指标
Prometheus 与示例应用在同一网络命名空间时可用以下抓取配置:
scrape_configs:
- job_name: spring-app
metrics_path: /actuator/prometheus
static_configs:
- targets: ["127.0.0.1:9091"]
自定义业务指标
Counter:累计计数
订单获受理时递增 checkout.accepted。Timer 已包含被计时调用的次数,这里的 Counter 单独回答“受理了多少订单”,口径不同。
Gauge:瞬时值
用 checkout.in.flight 观察抓取时刻的在途请求。示例把 AtomicInteger 保存在控制器字段,避免 Gauge 默认弱引用指向的对象被回收。两次抓取间的瞬时峰值可能看不到。Micrometer Gauge
Timer:耗时与分布
将以下代码保存为 src/main/java/example/checkout/CheckoutApplication.java。Timer 测量这段业务处理的耗时,两种结果都计入;250 毫秒是示例 SLO 桶边界。
package example.checkout;
import java.time.Duration;
import java.util.concurrent.atomic.AtomicInteger;
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.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
@SpringBootApplication
public class CheckoutApplication {
public static void main(String[] args) {
SpringApplication.run(CheckoutApplication.class, args);
}
}
@RestController
class CheckoutController {
private final MeterRegistry registry;
private final AtomicInteger inFlight = new AtomicInteger();
private final Counter accepted;
private final Timer duration;
CheckoutController(MeterRegistry registry) {
this.registry = registry;
accepted = registry.counter("checkout.accepted", "channel", "web");
Gauge.builder("checkout.in.flight", inFlight, AtomicInteger::get)
.register(registry);
duration = Timer.builder("checkout.duration")
.publishPercentileHistogram()
.serviceLevelObjectives(Duration.ofMillis(250))
.register(registry);
}
@PostMapping("/checkout/{orderId}")
ResponseEntity<Void> checkout(@PathVariable("orderId") String orderId) {
Timer.Sample sample = Timer.start(registry);
inFlight.incrementAndGet();
try {
if ("declined".equals(orderId)) {
return ResponseEntity.unprocessableEntity().build();
}
accepted.increment();
return ResponseEntity.noContent().build();
} finally {
inFlight.decrementAndGet();
sample.stop(duration);
}
}
}
分别执行 curl -X POST http://127.0.0.1:8080/checkout/42 与 curl -X POST http://127.0.0.1:8080/checkout/declined。在新进程中各执行一次,再抓取管理端点,checkout_accepted_total 增加 1,checkout_duration_seconds_count 增加 2。无其他请求时,checkout_in_flight 回到 0。
默认 Timer 暴露次数、总耗时与近期最大值等序列。启用 publishPercentileHistogram() 或配置合适的 SLO 桶才会输出可用于经典直方图查询的桶。以下 P95 估算使用秒为单位。合并不同实例时,确保被汇总的桶边界一致。Micrometer 直方图和分位数 · Prometheus 查询函数
histogram_quantile(
0.95,
sum by (le) (rate(checkout_duration_seconds_bucket{job="spring-app"}[5m]))
)
生产要点
- Actuator 端点别裸奔:独立管理端口只是把流量分开,并不提供鉴权。为远程采集配置可达的管理地址、网络访问控制和适当的认证。若应用自定义了
SecurityFilterChain,要在自己的规则里核对 Actuator 的访问权限。Spring Boot 管理端口与监听地址 - 标签基数:使用 Spring MVC 匹配到的路由模板(如
uri=/checkout/{orderId})。实际抓取中核对标签,别往自定义 tag 里塞业务 ID。 - JVM 指标盯什么:联看堆占用、GC 停顿和线程数。GC P99 需要先有可用于分位数查询的分布数据;堆或线程数上升只是排查线索。
常见问题(FAQ)
Q:Micrometer 和直接用 Prometheus Java 客户端有什么区别?
A:Micrometer 提供通用埋点 API,Spring Boot 可自动配置注册表。切换后端往往可以保留这些埋点,仍要核对指标名、标签、单位与查询。直接使用 Prometheus 客户端则使用其专用 API。
Q:JVM 堆一直涨是内存泄漏吗?
A:不一定。观察可比负载下 GC 后的堆占用趋势,区分缓存增长、负载变化等原因,再结合堆转储判断对象为何仍被引用。
Q:能看到 Tomcat 线程池状态吗?
A:使用嵌入式 Tomcat 时,Spring Boot 3.5 的 Tomcat 指标依赖启用 MBean 注册表(server.tomcat.mbeanregistry.enabled=true,默认关闭)。再核对抓取结果里的线程池标签与可用指标,例如 tomcat_threads_busy_threads、tomcat_threads_config_max_threads。忙线程接近上限可提示线程池压力,需结合持续时间和请求表现判断。