JavaPrometheus监控配置全攻略

本文深入解析了Java应用对接Prometheus监控的核心实践与常见陷阱：从依赖引入（micrometer-registry-prometheus）、Spring Boot中正确启用/actuator/prometheus端点（非/metrics！），到版本对齐、安全放行、K8s路由配置；同时厘清Counter与Gauge的本质区别及编码规范，避免指标语义错误导致PromQL失效；并系统排查404/401响应、数据拉取失败、命名混乱等高频问题，助你一次配通、长期稳定、精准可观测。

Java应用怎么暴露Prometheus指标端点

Java应用本身不自带Prometheus端点，必须引入micrometer-registry-prometheus并手动注册PrometheusMeterRegistry。Spring Boot 2.0+默认集成了Micrometer，但/actuator/prometheus端点默认不启用——光加依赖没用。

• 确认management.endpoints.web.exposure.include配置里包含prometheus（不是*就别偷懒，生产环境慎用通配）
• Spring Boot 3.x起，micrometer-registry-prometheus需与Micrometer 1.10+对齐，老项目升级时容易因版本错配导致BeanCreationException: Error creating bean with name 'prometheusMeterRegistry'
• 非Spring项目（如裸Jetty/Netty服务），得自己构造PrometheusMeterRegistry并挂到HTTP handler上，常见漏掉new PrometheusMeterRegistry(PrometheusConfig.DEFAULT)里的配置实例

为什么/metrics返回404但/actuator/health正常

这是路径和Actuator端点配置双重作用的结果。Spring Boot的management.endpoints.web.base-path默认是/actuator，所以Prometheus端点实际路径是/actuator/prometheus，不是/metrics——后者是旧版Dropwizard或早期Spring Boot 1.x的路径，硬改成/metrics需要额外配置management.endpoints.web.path-mapping.prometheus=metrics，但不推荐，易和反爬策略、网关路由冲突。

• 检查application.yml中是否遗漏management.endpoint.prometheus.show-details=always（调试时有用，但生产建议关）
• 若用Spring Security，需放行/actuator/prometheus，否则返回401而非404；先curl -v确认是404还是401
• Kubernetes里Service或Ingress未正确转发/actuator/.*前缀，也会表现为404

Counter和Gauge在Java代码里怎么选

选错类型会导致Prometheus查询结果完全失真。Counter只能增不能减，适合累计值（如请求总数、错误总次数）；Gauge可增可减，适合瞬时值（如当前活跃线程数、内存使用MB）。误把活跃连接数当Counter更新，下次重启后指标突降，PromQL的rate()直接崩掉。

• Counter.builder("http.requests.total").register(meterRegistry) —— 注册后只能调.increment()
• Gauge.builder("jvm.memory.used", memoryPool, p -> p.getUsage().getUsed()) —— 必须传入实时计算的lambda，不能传死值
• 避免在循环里反复.register()同一个名字的meter，会抛DuplicateMeterException；用meterRegistry.find("name").meter()先查再注册

Java应用启动后Prometheus拉不到数据

最常见原因是目标地址没配对，或者Java进程根本没开HTTP端点。Prometheus的scrape_configs里static_configs.targets填的是应用所在机器的IP+端口，不是localhost；容器环境更要确认是Pod IP还是Service DNS名，且目标端口必须和server.port或management.server.port一致（两者可不同）。

• 先在Java宿主机上curl http://localhost:8080/actuator/prometheus，能返回文本才说明端点活着
• 如果management.server.port单独设为8081，而scrape_configs仍写8080，必然超时
• JVM参数加-Djava.security.egd=file:/dev/./urandom，某些镜像缺这个会导致HTTPS握手卡住，连带HTTP端点响应极慢甚至失败

指标命名带jvm_前缀的，基本来自Micrometer自动绑定的JVM模块；自定义业务指标务必加业务前缀（如order.payment.success），不然和系统指标混在一起，后期查问题时根本分不清哪条是你写的。

今天关于《JavaPrometheus监控配置全攻略》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！