Prometheus最佳实践(一)——指标命名

Prometheus 指标命名最佳实践

本文档来自 Prometheus 官方文档 - Metric and label naming，虽非强制要求，但提供了指标（metric）和标签（label）命名的风格指南与最佳实践。

一、指标名称（Metric Names）

命名规则

• 字符合法性：必须符合 Prometheus 数据模型中对合法字符的要求。

• 前缀（命名空间）：

  • 应包含一个与指标所属领域相关的单字应用前缀（也称 namespace）。
  • 对于特定应用的指标，通常直接使用应用名作为前缀。
  • 示例：
    • prometheus_notifications_total（Prometheus 服务器特有）
    • process_cpu_seconds_total（多个客户端库通用）
    • http_request_duration_seconds（所有 HTTP 请求通用）

• 单位一致性：

  • 一个指标只能有一种单位（不能混用秒和毫秒、字节和千字节等）。

  • 应使用基本单位（base units），例如：

    • 时间：秒（seconds）
    • 存储：字节（bytes）
    • 长度：米（meters）
    • 温度：摄氏度（celsius）
    • 质量：克（grams）（避免千克以防止“kilo”前缀混淆）
    • 电压：伏特（volts）
    • 电流：安培（amperes）
    • 能量：焦耳（joules）

• 单位后缀：

  • 单位应以复数形式作为后缀（如 _seconds、_bytes）。

  • 累计计数器需加

    _total

    后缀（若带单位，则单位在

    _total

    前）：

    • http_requests_total（无单位计数）
    • process_cpu_seconds_total（带单位的累计值）

  • 特殊伪指标（metadata）可不遵循单位规则：

    • foobar_build_info
    • data_pipeline_last_record_processed_timestamp_seconds

• 排序友好性：

  • 可调整名称组件顺序，使相关指标在字典序排序时聚集在一起。
  • 推荐：公共部分在前
    ✅ prometheus_tsdb_head_truncations_closed_total
    ✅ prometheus_tsdb_head_truncations_established_total
  • 不推荐：可读性好但排序分散
    ❌ prometheus_tsdb_head_closed_truncations_total

• 语义一致性：

  • 同一指标在所有标签维度下应表示同一逻辑事物。

    • 如：请求耗时、传输字节数、瞬时资源使用率（百分比）

  • 经验法则：对该指标的所有标签维度做

    sum()

    或

    avg()

    应具有意义。

    • ✅ 各队列容量 → 可汇总

  • ❌ 队列容量 + 当前元素数量 → 应拆分为两个指标

---

二、标签（Labels）

使用原则

• 用途：用于区分被测量对象的不同特征。

  • 示例：
    • api_http_requests_total{operation="create|update|delete"}
    • api_request_duration_seconds{stage="extract|transform|load"}

• 禁止冗余：

  • 不要将标签名写入指标名称中（如 http_requests_by_operation_total），否则在聚合时会造成混淆。

• 警惕高基数（High Cardinality）：

  • 每个唯一的标签键值对都会创建一个新的时间序列。

  • 避免使用高基数标签，如：

    • 用户 ID
    • 邮箱地址
    • 会话 ID
    • 任意无界字符串

  • 否则会导致存储爆炸和性能下降。

---

三、单位规范（Base Units）

Prometheus 不内置单位，为保证兼容性，应统一使用以下基本单位：

类别	基本单位	说明
时间	seconds
温度	celsius	实用场景优先；绝对温度可用 kelvin
长度	meters
存储	bytes	即使习惯用 bits，也统一用 bytes
百分比	ratio	值范围 0–1；命名如 disk_usage_ratio，或使用 A_per_B 形式
电压	volts
电流	amperes
能量	joules
功率	—	建议导出 joules 计数器，再用 rate(joules[5m]) 得到瓦特（Watts）
质量	grams	避免 kg 引发前缀歧义