Prometheus与Micrometer监控配置教程

本文深入解析了在Spring Boot应用中正确集成Prometheus与Micrometer实现Java服务监控的关键实践与常见陷阱：从依赖组合（必须同时引入spring-boot-starter-actuator和micrometer-registry-prometheus）、端点暴露配置（management.endpoints.web.exposure.include需显式声明）、Prometheus抓取路径（metrics_path必须为/actuator/prometheus）到@Timed注解生效条件（依赖Spring AOP代理、public方法及容器管理Bean），再到自定义指标的规范设计（避免动态长文本Tag、统一使用Tags.of()、上线前通过/actuator/metrics逐级验证），层层拆解运维中高频报错的根源——不是代码写错了，而是环境配漏了、路径写偏了、标签用滥了。掌握这些细节，才能让每一条监控数据真正落地、可查、可持续。

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学习网公众号，给大家分享更多文章知识！