Micrometer依赖需同时引入spring-boot-starter-actuator和对应registry（如micrometer-registry-prometheus），并配置management.endpoints.web.exposure.include显式暴露端点；Prometheus的scrape_config中metrics_path必须设为/actuator/prometheus；@Timed依赖Spring AOP代理，须确保方法由容器注入且为public；自定义指标应规范使用Tags避免动态长文本，上线前用/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 设计和端点连通性，往往比写代码花的时间多得多。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
