指标命名规范：让 Prometheus 数据可读、可聚合

指标一旦被看板、告警和 SLO 引用，重命名成本会迅速上升。发布前约束命名和标签，比事后清理时间序列更便宜。

命名表达完整语义

推荐结构为 <namespace>_<subsystem>_<name>_<unit>。累计值使用 base unit 和 _total，时长用 seconds，字节用 bytes。

checkout_http_requests_total
checkout_http_request_duration_seconds
checkout_queue_messages
checkout_build_info{version="1.8.2"} 1

Counter 表示单调累积事件，Gauge 表示可升可降状态。不要用 Gauge 模拟请求总数，也不要把毫秒和秒混在同一指标族。

标签只描述有限维度

http_requests_total{method="GET",route="/orders/:id",code="200"}

使用模板化 route，不放 user_id、request_id、原始 URL 或错误消息。若标签值会随业务规模无界增长，它更适合作为日志字段或 trace attribute。

发布前评审

• 指标名是否包含明确单位和业务前缀
• 类型是否符合数值语义
• 每个标签的可能取值是否有上界
• help 文本是否说明测量对象和边界
• 删除或重命名是否提供迁移窗口

收尾清单

在 CI 中用 promtool check metrics 和自定义规则检查格式。为指标建立 owner 与弃用流程，避免同一含义长期存在多个名称。