Actuator、Micrometer 与指标埋点：状态怎样变成可聚合信号

Actuator、Micrometer 与指标埋点：状态怎样变成可聚合信号高清原图

指标设计先决定聚合问题，再选择 Meter 与标签。

Micrometer 的 Meter 概念 区分 Timer、Counter 与 Gauge；Spring Boot 的 Observability 说明 Observation 和低/高基数键。

故障现场：团队把 userId、原始 URL 和异常消息作为 tag，时间序列随请求增长；同时用 Gauge 表示累计请求，采样间隔内的变化全部消失。

团队把 userId、原始 URL 和异常消息作为 tag，时间序列随请求增长；同时用 Gauge 表示累计请求，采样间隔内的变化全部消失。 先画出事件从业务动作到查询结果的完整路径，逐段记录输入、输出、队列水位、丢弃策略和关联键。最危险的不是显式报错，而是应用成功、遥测静默缺失；缺失必须变成可告警状态，不能用“平台偶尔延迟”长期解释。

权威状态与观测结论必须分开

Counter 观察单调事件并在查询端求 rate；Timer 同时携带 count 与 duration；Gauge 只表示当前可重建状态。成功率由总量和错误量同窗计算，不能把百分比先平均。 对每个结论列出反证：字段缺失时还能否区分业务拒绝与系统异常，关联断开时能否从消息或 operationId 恢复，采样后统计是否仍代表总体。信号只能证明其观测窗口内发生了记录，不能证明未记录的事件不存在。

建模主链与边界条件

Question

在 Question 阶段固定 owner、输入、输出、失败原因和容量上限。正向用例证明正常状态产生唯一且稳定的证据；反向用例分别删除上下文、制造未知字段、填满队列或扩大标签空间，断言缺口被计数且不会污染业务线程。字段名和结果枚举一旦进入告警与查询就是契约，修改必须兼容迁移。

Instrument

在 Instrument 阶段固定 owner、输入、输出、失败原因和容量上限。正向用例证明正常状态产生唯一且稳定的证据；反向用例分别删除上下文、制造未知字段、填满队列或扩大标签空间，断言缺口被计数且不会污染业务线程。字段名和结果枚举一旦进入告警与查询就是契约，修改必须兼容迁移。

Low-card tags

在 Low-card tags 阶段固定 owner、输入、输出、失败原因和容量上限。正向用例证明正常状态产生唯一且稳定的证据；反向用例分别删除上下文、制造未知字段、填满队列或扩大标签空间，断言缺口被计数且不会污染业务线程。字段名和结果枚举一旦进入告警与查询就是契约，修改必须兼容迁移。

Aggregate

在 Aggregate 阶段固定 owner、输入、输出、失败原因和容量上限。正向用例证明正常状态产生唯一且稳定的证据；反向用例分别删除上下文、制造未知字段、填满队列或扩大标签空间，断言缺口被计数且不会污染业务线程。字段名和结果枚举一旦进入告警与查询就是契约，修改必须兼容迁移。

SLO window

在 SLO window 阶段固定 owner、输入、输出、失败原因和容量上限。正向用例证明正常状态产生唯一且稳定的证据；反向用例分别删除上下文、制造未知字段、填满队列或扩大标签空间，断言缺口被计数且不会污染业务线程。字段名和结果枚举一旦进入告警与查询就是契约，修改必须兼容迁移。

Alert proof

在 Alert proof 阶段固定 owner、输入、输出、失败原因和容量上限。正向用例证明正常状态产生唯一且稳定的证据；反向用例分别删除上下文、制造未知字段、填满队列或扩大标签空间，断言缺口被计数且不会污染业务线程。字段名和结果枚举一旦进入告警与查询就是契约，修改必须兼容迁移。

从用户问题反推信号，而不是从采集能力出发

一条信号必须拥有完整生命周期

基数、体积和保留期是运行时资源

敏感数据和攻击面进入信号设计

Actuator 与遥测导出端点也是管理面：健康详情、配置、线程、堆和指标可能暴露拓扑与业务规模。管理端口、网络策略、认证授权和审计独立设计；公开健康只给负载均衡所需结论，深度诊断要求内部身份。远端传入 trace/baggage 先校验格式、长度和允许键，不能让攻击者制造高基数或伪造租户上下文。

用故障注入验证信号而不是看一次漂亮页面

查询、告警与恢复必须共享同一语义

两个 Java 17 模型固定可重复见证

模型不依赖日志平台、指标后端或 Collector，只压缩该主题最关键的状态转换和量化判据。真实工程用 SLF4J、Logback、Micrometer 或 OpenTelemetry 驱动同一不变量。

javac --release 17 -Xlint:all -Werror examples/backend-development/observability/metrics-actuator-micrometer/MeterSemanticsDemo.java examples/backend-development/observability/metrics-actuator-micrometer/CardinalityBudgetDemo.java
java -cp examples/backend-development/observability/metrics-actuator-micrometer MeterSemanticsDemo
java -cp examples/backend-development/observability/metrics-actuator-micrometer CardinalityBudgetDemo

requests=4 errors=1 totalMillis=140 maxMillis=80 errorRate=0.25 timerCarriesCount=true
routeTemplates=3 methods=2 outcomes=4 upperBound=24 rawUserIdsRejected=1000 budgetSafe=true

输出变化必须能归因于信号契约、容量策略或业务规格，不能通过删除字段、扩大采样或无限重试吸收差异。

容量、发布与恢复门禁

在埋点前计算标签笛卡尔积上界，并观察实际 active series、溢出和注册表内存；直方图桶按 SLO 阈值设计，客户端分位数通常不能跨实例聚合。 发布前用峰值输入和故障放大系数计算容量，在预发布环境制造后端慢、连接中断和停机，验证业务延迟、遥测缺口和恢复时间。指标改名或改标签先并行发布新旧序列，仪表盘与告警切换后等待完整窗口再删除；Actuator 暴露面与业务端口分离并执行最小授权。

门禁同时检查信号存在、语义正确、关联完整、基数受控、敏感字段缺失和故障时可恢复。围绕“每个指标回答一个可聚合问题，标签空间有界，告警能够映射到用户影响和处置动作”记录 owner、预算、保留期、告警消费者和最近一次真实发现；没有消费者且不能回答诊断问题的信号应删除，而不是永久堆积。