Prometheus与Micrometer监控配置教程

本文深入解析了在Spring Boot应用中正确搭建Java监控环境的关键实践，涵盖Micrometer与Prometheus集成的四大核心痛点：依赖配置（必须同时引入spring-boot-starter-actuator和对应registry，缺一不可）、Prometheus抓取路径精准对齐（metrics_path务必设为/actuator/prometheus）、@Timed注解生效前提（依赖Spring AOP代理，需public方法+容器管理+避免内部调用），以及自定义指标的规范设计（标签命名严谨、规避动态长文本、上线前通过/actuator/metrics验证结构）。每一步都直击生产环境中最常见的404、数据缺失、切面失效和查询爆炸等真实陷阱，帮你少踩坑、快落地、稳监控。

micrometer依赖加对了吗？别漏掉actuator

Spring Boot 2.0+ 默认用 Micrometer 做指标抽象，但光引 micrometer-core 不行，必须搭配 spring-boot-starter-actuator 才能暴露 /actuator/metrics 端点。常见错误是只加了监控客户端（比如 micrometer-registry-prometheus），却没开 actuator，结果访问 /actuator/prometheus 直接 404。

• 务必在 pom.xml 中同时包含：spring-boot-starter-actuator 和 micrometer-registry-prometheus
• 检查 application.yml 是否放开端点：management.endpoints.web.exposure.include: prometheus,health,info
• Spring Boot 3.x 起默认关闭所有端点，exposure.include 必须显式声明，不能只写 prometheus —— 否则 /actuator/health 也访问不了，排查时容易误判

为什么Prometheus拉不到Java应用的指标？

最常卡在路径、端口、网络三处。Prometheus 不是自动发现 Java 应用的，得靠配置明确告诉它“去哪拉”。默认 micrometer-registry-prometheus 把指标挂到 /actuator/prometheus，但 Prometheus 的 scrape_config 如果写成 metrics_path: /metrics 就会 404。

• 确认 Java 应用启动后能直接 curl 通：curl http://localhost:8080/actuator/prometheus（注意不是 /metrics）
• Prometheus 配置里 scrape_configs 的 metrics_path 必须设为 /actuator/prometheus
• 如果 Java 应用跑在 Docker 或 k8s 里，注意 host.docker.internal 或 service DNS 是否可达；本地调试时别忘了把 application.yml 中的 management.server.port 和主服务端口区分开，避免冲突

@Timed 注解没生效？检查切面是否被代理

@Timed 是 Micrometer 提供的方法级耗时统计，但它依赖 Spring AOP。如果目标方法是本类内部调用（比如 this.doWork()），或者类没被 Spring 管理（new 出来的实例），注解就完全不触发。

• 确保被注解的方法是 public，且由 Spring 容器注入调用（比如通过 @Autowired 注入的 bean）
• 非 Web 层方法想用 @Timed，要确认项目启用了 AspectJ 或已引入 spring-boot-starter-aop
• 更稳的方式是手动用 Timer.Sample：在方法开头 Timer.Sample sample = Timer.start(meterRegistry)，结尾 sample.stop(timer)，绕过 AOP 限制

指标命名混乱、查不到数据？从 meterId 规范开始

Micrometer 默认生成的指标名（如 http.server.requests）看着合理，但自定义指标一旦用错 Tag 或 description，Prometheus 查询时就难过滤、易歧义。比如用 Tag.of("status", "200") 没问题，但写成 Tag.of("status", String.valueOf(statusCode)) 却可能混入 "200.0" 这种浮点字符串，导致 label 不匹配。

• 所有自定义 Counter/Timer 创建时，优先用 meterRegistry.counter("my.op.count", Tags.of(...))，别拼接字符串
• 避免在 tag value 里塞动态长文本（如用户 ID、URL 路径），容易撑爆 Prometheus 内存；高频维度用 tag，低频或不定长内容改用 log 或 trace
• 上线前用 curl /actuator/metrics 看指标列表，再选一个具体指标查 /actuator/metrics/{name}，确认 tags 结构和值类型符合预期

指标打点逻辑本身不难，难的是让每条数据在 Prometheus 里可查、可比、不爆炸。tag 设计和端点连通性，往往比写代码花的时间多得多。

到这里，我们也就讲完了《Prometheus与Micrometer监控配置教程》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！