可观测性与稳定性 / 系统课时
指标名称应该怎样设计
指标名称应该怎样设计
指标名称一旦进入告警、仪表盘和长期存储,后续改名成本很高。本篇给出一套可直接执行的命名原则,让同一名称始终表达同一种含义、单位和统计方式。
学习目标
- 按 Prometheus 习惯为指标选择清晰稳定的名称
- 正确表达单位、累计计数和命名空间
- 识别会导致查询困难或语义冲突的命名方式
名称先表达测量对象
一个好名称应该让读者在没有上下文时也能大致判断“测量什么”。通常采用小写单词和下划线,例如 http_request_duration_seconds、process_resident_memory_bytes。
名称里应放稳定的测量语义,不要把会变化的维度塞进去。比如不要分别创建 http_requests_login_total、http_requests_checkout_total,更适合使用同一个指标名,再通过标签区分路由:
http_requests_total{route="/login"} 1280
http_requests_total{route="/checkout"} 420这是格式示例,表示同一种“HTTP 请求累计次数”通过 route 标签区分业务路径。这样查询可以统一写成 sum by (route) (http_requests_total),而不是提前知道所有可能出现的指标名。
单位要写进名称
当指标表示可换算的物理量时,名称通常应包含基本单位,并使用复数形式。时间优先使用秒,数据大小优先使用字节。例如:
| 含义 | 推荐名称 | 不推荐 |
|---|---|---|
| 请求耗时 | http_request_duration_seconds |
http_request_duration_ms |
| 响应体大小 | http_response_size_bytes |
http_response_size_kb |
| 进程启动时间 | process_start_time_seconds |
process_start_timestamp |
统一基本单位的价值在于,查询和仪表盘不必猜测不同服务到底使用毫秒、秒、KB 还是 MB。展示层需要毫秒或 MiB 时,再在 PromQL 或 Grafana 中换算。
Counter 用 total 表达累计语义
持续累计且通常只增不减的 Counter,名称应以 _total 结尾,例如 http_requests_total、errors_total。这样看到名称就能判断它适合配合 rate()、increase() 等函数分析变化速度或区间增量。
Gauge 不使用 _total 来伪装累计值。当前温度、队列长度、并发连接数等可升可降的量,应直接描述当前状态,例如 queue_depth、active_connections。
用前缀建立命名空间
当一个服务暴露很多自定义指标时,可以使用稳定前缀标识所属组件,例如 checkout_orders_total、checkout_payment_failures_total。前缀的目标是减少冲突,不是把组织架构全部编码进名称。
环境、区域、实例、状态码等可枚举维度更适合作为标签,而不是名称的一部分。否则会把一个逻辑指标拆成大量彼此独立的名字,查询、告警和聚合都会变复杂。
同名指标必须保持同一种语义
最危险的问题不是名字不好看,而是同一个名称在不同服务里代表不同东西。例如某服务把 request_duration_seconds 记录为平均值,另一个服务却把同名指标当作单次请求直方图的一部分,跨服务聚合时就会产生误导。
设计前可以用三个问题做最终检查:这个名称是否明确描述测量对象;单位是否统一且写进名称;相同名称在所有产生它的组件中是否保持相同含义和类型。只要这三点稳定,后续 PromQL、告警规则和 Grafana 面板都会更容易维护。