Java 应用接入 Prometheus 监控(Spring Boot 实战)

Spring Boot 接入 Prometheus:Micrometer + Actuator 暴露 /actuator/prometheus、JVM 默认指标解读、Counter/Gauge/Timer 自定义埋点与生产配置要点。

最佳实践
Java 应用接入 Prometheus 监控(Spring Boot 实战)技术指南封面

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]))
)

生产要点

  1. Actuator 端点别裸奔:独立管理端口只是把流量分开,并不提供鉴权。为远程采集配置可达的管理地址、网络访问控制和适当的认证。若应用自定义了 SecurityFilterChain,要在自己的规则里核对 Actuator 的访问权限。Spring Boot 管理端口与监听地址
  2. 标签基数:使用 Spring MVC 匹配到的路由模板(如 uri=/checkout/{orderId})。实际抓取中核对标签,别往自定义 tag 里塞业务 ID。
  3. 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。忙线程接近上限可提示线程池压力,需结合持续时间和请求表现判断。

获取专属方案

联系我们

加入社区

微信扫码
加入官方交流群

立即体验

在线开通,按量计费,真正的云服务!

立即开始

选择观测云版本

代码托管平台