📚 课程目录第4章 Metric命名规范

4. Metric命名规范：Prometheus命名最佳实践、命名空间、单位、语义化命名

Metric 命名是可观测性体系中最容易被忽视、却影响最深远的环节。一个规范的 Metric 名称，能让告警规则、Dashboard 面板、跨团队协作的效率提升数倍；反之，混乱的命名会导致告警误报、查询歧义、数据孤岛。本节将系统讲解 Prometheus 官方命名最佳实践，并结合告警聚合场景，给出可落地的命名规范。

4.1 核心原则：命名空间、单位、语义化

Prometheus 官方建议 Metric 名称遵循以下三层结构：

层级	说明	示例
命名空间	标识 Metric 所属的组件、层级或业务域，避免全局冲突	`node_`、`prometheus_`、`nginx_`、`api_`
基础名称	描述被测量的对象或指标，使用单数形式	`http_requests_total`、`cpu_seconds_total`
单位后缀	明确 Metric 的计量单位，Prometheus 推荐使用标准单位	`_seconds`、`_bytes`、`_total`、`_ratio`

核心公式：<namespace>_<name>_<unit>。例如 node_memory_MemTotal_bytes 表示 node 命名空间下内存总量，单位 bytes。

4.2 命名空间设计：分层与隔离

命名空间是 Metric 命名的第一道防线。在告警聚合场景中，命名空间决定了告警的归属范围和聚合粒度。推荐采用 层级命名空间 策略：

基础设施层：node_、kube_、container_
中间件层：nginx_、redis_、mysql_
应用层：api_、order_、payment_
业务层：business_、user_、transaction_

  告警聚合场景下的命名空间设计要点：
  同一告警规则应只匹配单一命名空间的 Metric，避免跨层聚合导致语义混淆。
命名空间层级不宜超过 3 层，例如 prod_api_http_requests_total 优于 prod_us_east_api_http_requests_total。
环境信息（prod/staging）应通过 Label 表达，而非嵌入命名空间。

4.3 单位后缀规范：标准单位与转换

Prometheus 推荐使用 SI 标准单位，并在 Metric 名称末尾显式标注。这能避免 Dashboard 和告警规则中的单位歧义。

测量类型	推荐单位	Metric 后缀	错误示例
时间	秒 (seconds)	`_seconds`	`_milliseconds`、`_ms`
数据量	字节 (bytes)	`_bytes`	`_kb`、`_mb`
计数	无单位 (total)	`_total`	`_count`（Counter 类型专用）
比率	无单位 (ratio)	`_ratio`	`_percent`、`_pct`
速率	每秒 (per second)	`_per_second`	`_rate`（函数名，非单位）

常见陷阱：不要将单位缩写（如 _ms、_kb）作为后缀。Prometheus 的 PromQL 函数（如 rate()、increase()）默认以秒为单位，非标准单位会导致计算错误。

4.4 语义化命名：可读性与一致性

语义化命名要求 Metric 名称能够“自解释”，即使不查看文档，也能大致理解其含义。以下是语义化命名的关键规则：

使用下划线分隔单词：http_requests_total 而非 httpRequestsTotal 或 http-requests-total。
名称顺序：从通用到具体：node_network_receive_bytes_total 优于 receive_bytes_network_node_total。
避免冗余信息：命名空间已包含的信息不要在基础名称中重复。例如 node_cpu_seconds_total 而非 node_node_cpu_seconds_total。
Counter 类型必须加 _total 后缀：这是 Prometheus 的硬性约定，用于区分 Counter 和 Gauge。
Histogram/Summary 的桶和分位数：桶使用 _bucket，分位数使用 _quantile。

  告警聚合场景下的语义化命名建议：
  告警规则中频繁使用的 Metric，名称应尽量短且含义明确，例如 error_ratio 优于 service_error_count_per_total_requests_ratio。
对于聚合告警，建议在命名空间中体现聚合层级，例如 cluster_cpu_usage_ratio 表示集群级别的 CPU 使用率。

4.5 命名规范与告警聚合的协同

当 Metric 命名规范与告警聚合规则协同设计时，可以显著降低告警规则的复杂度。以下是一个协同设计的示例：

# 不规范的命名
# 命名空间混乱，单位缺失，语义模糊
http_requests{status="500", env="prod"} 5
http_requests{status="200", env="prod"} 100
error_count{env="prod"} 5

# 规范的命名
# 命名空间清晰，单位明确，语义自解释
api_http_requests_total{status="500", env="prod"} 5
api_http_requests_total{status="200", env="prod"} 100
api_http_errors_total{env="prod"} 5

# 告警规则可以直接复用命名空间进行聚合
# 例如：sum by (env) (api_http_errors_total) > 10

4.6 命名规范检查清单

在团队中推行 Metric 命名规范时，可以使用以下检查清单进行评审：

检查项	通过标准	常见违规
命名空间	存在且唯一，不超过 3 层	无命名空间、命名空间重复
单位后缀	使用 SI 标准单位，显式标注	使用缩写、无单位后缀
Counter 后缀	Counter 类型必须加 `_total`	Counter 无 `_total` 后缀
单词分隔	使用下划线，小写字母	驼峰命名、连字符、大写字母
语义自解释	名称可独立理解含义	依赖 Label 才能理解
Label 与命名空间	环境、地域等通过 Label 表达	环境信息嵌入命名空间

4.7 命名规范落地流程

为了确保命名规范在团队中落地，建议采用以下流程：

制定团队规范文档：基于 Prometheus 官方最佳实践，结合业务场景定制。
代码审查强制检查：在 CI/CD 流水线中加入 Metric 命名规范检查脚本。
定期审计与重构：每季度对现有 Metric 进行审计，逐步淘汰不合规的命名。
自动化工具辅助：使用 promtool 或自定义 Linter 进行静态检查。

推荐工具：Prometheus 官方提供的 promtool check metrics 命令可以检查 Metric 命名是否符合基本规范。对于更复杂的语义检查，可以结合 yaml-language-server 和自定义规则。

4.8 常见命名反模式与修正

反模式	错误示例	正确示例	说明
无命名空间	`cpu_usage_ratio`	`node_cpu_usage_ratio`	无法区分来源组件
单位缩写	`response_time_ms`	`http_response_time_seconds`	PromQL 函数默认秒单位
驼峰命名	`httpRequestsTotal`	`http_requests_total`	Prometheus 推荐下划线
环境嵌入命名空间	`prod_api_http_requests_total`	`api_http_requests_total{env="prod"}`	环境应通过 Label 表达
Counter 无 total 后缀	`http_requests`	`http_requests_total`	违反 Prometheus 约定
名称顺序混乱	`total_bytes_receive_network_node`	`node_network_receive_bytes_total`	从通用到具体

特别提醒：在告警聚合场景中，反模式 Metric 会导致告警规则难以编写和维护。例如，prod_api_http_requests_total 和 staging_api_http_requests_total 是两个不同的 Metric，无法通过一个 sum by (env) 聚合，必须分别写两条告警规则。

4.9 命名规范自动化检查

为了在团队中持续执行命名规范，建议在 CI/CD 流水线中加入自动化检查。以下是一个基于 promtool 的检查脚本示例：

#!/bin/bash
# Metric 命名规范检查脚本
# 使用 promtool 检查 Metric 命名是否符合规范

# 检查 Counter 类型是否包含 _total 后缀
promtool check metrics --rules=metrics_rules.yaml metrics.txt

# 自定义检查：命名空间必须存在
grep -E '^[a-z]+_' metrics.txt || {
  echo "ERROR: Metric 缺少命名空间前缀"
  exit 1
}

# 自定义检查：禁止使用驼峰命名
grep -E '[A-Z]' metrics.txt && {
  echo "ERROR: Metric 名称包含大写字母，应使用下划线分隔"
  exit 1
}

echo "Metric 命名规范检查通过"

进阶建议：对于大型团队，可以开发基于 yaml-language-server 的 Linter 插件，在代码编辑阶段实时提示命名规范问题，将问题消灭在源头。