指标命名与标签应该如何规范？

简化版

指标名应稳定表达领域、对象、度量和单位，标签承载有限的查询维度。名称、类型、单位、标签值域和 owner 都要登记；禁止把单位或状态动态拼进名称，也禁止 userId、requestId 等无界标签。

详细版

Counter 使用累计总量，Gauge 表示可升降状态，Histogram 记录分布；在 Prometheus 暴露格式中 Counter 通常以 _total 表意。时间统一 seconds、字节统一 bytes，避免同名不同单位；标签采用 route template、method、status_code、region 等有限枚举。

指标变更视为契约演进：先双发新旧指标，迁移告警与看板，确认旧查询归零后清理。通过 lint、注册表和基数预算在 CI 守门，并记录帮助文本与 owner。

完整版教学

一、为什么命名是契约

告警、看板和容量模型都会依赖指标。一处随意 rename 会让监控静默失明，因此指标不仅是代码细节，也是长期数据接口。

记忆钩子：名字说“测什么”，类型说“怎样变化”，标签说“按什么切分”。

二、组成规则

<namespace>_<subsystem>_<measurement>_<unit>
checkout_payment_duration_seconds
checkout_payment_attempts_total

名称不要包含环境和状态，prod_success_count 应改成稳定名称加 env、result 标签。

三、类型必须匹配语义

类型	示例	易错点
Counter	请求累计数	进程重启会归零
Gauge	队列长度	不用于累计次数
Histogram	请求时延	bucket 需规划
Info	构建版本	标签保持有限

平均延迟不能替代 Histogram，因为平均值掩盖长尾。

四、单位统一

一个服务上报毫秒、另一个上报秒，会让聚合失真。名称明确 _seconds、_bytes，数值使用基本单位；展示层再换算成人类友好格式。

例如 250ms 应上报 0.25 seconds，而非在同一指标里混合 250 与 0.25。

五、标签设计

标签只放有限、稳定、确实用于聚合的维度。原始 /orders/123 应归一为 /orders/:id；异常信息用 error_code，完整堆栈进日志。

新增标签前估算组合数，并确认缺失值语义。空字符串、UNKNOWN 和 NOT_APPLICABLE 不应混为一谈。

六、演进和治理

改名时双发 2 个指标，迁移 recording rule、告警和看板，再通过查询日志确认旧名无人使用。直接删除会产生无告警的监控空洞。

CI 检查名称、单位、类型和标签白名单；运行时监控新序列速率。指标目录记录说明、owner、SLO 用途和弃用日期。

跨语言 SDK 需要统一语义约定，避免 Java 写 status=success、Go 写 result=ok，导致同一看板无法聚合。

录制规则生成的新指标也要遵守命名与 owner 规范，不能成为绕开埋点治理的第二套体系。

七、常见误区与追问

• 误区：指标名越短越方便。 缺少领域和单位会产生歧义。
• 误区：状态放进指标名更直观。 会制造大量动态指标，应使用有限标签。
• 误区：平均值足够监控延迟。 长尾会被掩盖。
• 误区：加标签不影响已有查询。 聚合语义和序列数量都会变化。
• 追问：为何 Counter 重启归零仍可用？ 查询计算时间窗口内的增量并处理 reset。
• 追问：Histogram bucket 怎么选？ 围绕 SLO 阈值与实际分布压测。
• 追问：如何安全改名？ 双发、迁移依赖、观察归零、再删除。

八、加强记忆

指标规范用“稳定名称、正确类型、统一单位、有限标签、可治理演进”串联。名称不携带动态值，实体明细进入日志/Trace；指标像 API 一样登记 owner、兼容迁移和弃用证据，才能让告警与看板长期可信。