Back to Details

182-java-observability-metrics-micrometer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Java Metrics Observability with Micrometer

使用Micrometer实现Java指标可观测性

Implement effective Java metrics instrumentation with Micrometer by defining meaningful service-level metrics, controlling cardinality, selecting the right meter type, and exposing production-ready telemetry for dashboards and alerting.
What is covered in this Skill?
  • Metrics-first observability with Micrometer in Java applications
  • Meter selection: Counter, Timer, DistributionSummary, Gauge, LongTaskTimer
  • Naming and tagging conventions with low-cardinality dimensions
  • Cardinality and meter lifecycle safeguards to prevent time-series explosion
  • Histogram/percentile strategy and SLO-oriented metrics design
  • Integration guidance for Actuator + Prometheus/OpenTelemetry pipelines
  • Testing and verification of metrics registration and values
Scope: Application-level metrics design and instrumentation quality for Java services, with emphasis on operationally useful and cost-efficient telemetry.
通过定义有意义的服务级指标、控制基数、选择合适的计量器类型，并为仪表盘和告警提供可用于生产环境的遥测数据，从而基于Micrometer实现高效的Java指标埋点。
本技能涵盖哪些内容？
  • Java应用中基于Micrometer的指标优先可观测性方案
  • 计量器类型选择：Counter、Timer、DistributionSummary、Gauge、LongTaskTimer
  • 低基数维度的命名与标签规范
  • 防止时间序列爆炸的基数与计量器生命周期防护措施
  • 直方图/百分位数策略及面向SLO的指标设计
  • Actuator + Prometheus/OpenTelemetry流水线的集成指南
  • 指标注册与数值的测试验证
适用范围：Java服务的应用级指标设计与埋点质量优化，重点关注具备运维价值且成本高效的遥测数据。

Constraints

约束条件

Metrics instrumentation must be operationally safe, low-cardinality, and validated. Poor tag design or excessive meter creation can degrade observability systems and increase costs.
  • LOW CARDINALITY FIRST: Never tag metrics with unbounded values (userId, UUID, raw URL, full exception message)
  • RIGHT METER TYPE: Use Counter for monotonically increasing events, Timer for latency, Gauge for point-in-time state, and DistributionSummary for sampled values
  • BEFORE APPLYING: Read the reference for good/bad instrumentation examples and anti-patterns
  • VERIFY: Run 
    ./mvnw clean verify
    or 
    mvn clean verify
    after changes
指标埋点必须具备运维安全性、低基数特性，并经过验证。不合理的标签设计或过量创建计量器会降低可观测性系统性能并增加成本。
  • 优先低基数（LOW CARDINALITY FIRST）：切勿使用无界值（如userId、UUID、原始URL、完整异常信息）作为指标标签
  • 匹配正确计量器类型：使用Counter记录单调递增事件，Timer记录延迟，Gauge记录瞬时状态，DistributionSummary记录采样值
  • 应用前须知：查阅参考文档了解埋点的正反示例与反模式
  • 验证要求：修改后执行 
    ./mvnw clean verify
    或 
    mvn clean verify

When to use this skill

适用场景

  • Improve metrics
  • Apply Micrometer
  • Add metrics observability
  • Refactor Micrometer instrumentation
  • 改进指标体系
  • 应用Micrometer实现埋点
  • 添加指标可观测性能力
  • 重构Micrometer埋点代码

Workflow

工作流程

  1. Define measurement goals and meter contract
Identify key service indicators (throughput, latency, error ratio, saturation) and map each to stable metric names, units, and low-cardinality tags.
  1. Select meter types and instrument code paths
Apply Counter/Timer/Gauge/DistributionSummary/LongTaskTimer where appropriate, ensuring consistent naming conventions and reusable tags.
  1. Harden instrumentation for production
Control cardinality, avoid dynamic meter churn, configure histogram/percentile strategy only where needed, and align export settings with the telemetry backend.
  1. Validate and operationalize metrics
Verify metrics in tests and runtime endpoints, confirm expected labels/units, and ensure dashboards/alerts can consume the emitted series.
  1. 定义测量目标与计量器约定
识别关键服务指标（吞吐量、延迟、错误率、饱和度），并将每个指标映射为稳定的指标名称、单位与低基数标签。
  1. 选择计量器类型并埋点代码路径
在合适位置应用Counter/Timer/Gauge/DistributionSummary/LongTaskTimer，确保命名规范一致且标签可复用。
  1. 强化埋点以适配生产环境
控制基数、避免动态计量器频繁变化，仅在必要时配置直方图/百分位数策略，并使导出设置与遥测后端对齐。
  1. 验证并启用指标
在测试环境与运行时端点验证指标，确认标签/单位符合预期，并确保仪表盘/告警能正常接收生成的时间序列数据。

Reference

参考文档

For detailed guidance, examples, and constraints, see references/182-java-observability-metrics-micrometer.md.
如需详细指南、示例与约束说明，请查看 references/182-java-observability-metrics-micrometer.md。