Prometheus命名规范 #

命名规范的重要性：

┌─────────────────────────────────────────────┐
│ 1. 可读性                                   │
├─────────────────────────────────────────────┤
│ • 一眼就能理解指标含义                      │
│ • 降低学习成本                              │
│ • 便于团队协作                              │
├─────────────────────────────────────────────┤
│ 2. 一致性                                   │
├─────────────────────────────────────────────┤
│ • 统一的命名风格                            │
│ • 便于跨项目使用                            │
│ • 减少混淆                                  │
├─────────────────────────────────────────────┤
│ 3. 可维护性                                 │
├─────────────────────────────────────────────┤
│ • 易于查找和修改                            │
│ • 便于自动化处理                            │
│ • 减少错误                                  │
└─────────────────────────────────────────────┘

基本命名规则：

┌─────────────────────────────────────────────┐
│ 指标名称规则                                │
├─────────────────────────────────────────────┤
│ • 匹配正则：[a-zA-Z_:][a-zA-Z0-9_:]*       │
│ • 使用snake_case命名                        │
│ • 以字母开头                                │
│ • 冒号保留给规则名称                        │
│ • 不以数字开头                              │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ 标签名称规则                                │
├─────────────────────────────────────────────┤
│ • 匹配正则：[a-zA-Z_][a-zA-Z0-9_]*         │
│ • 使用snake_case命名                        │
│ • 以字母或下划线开头                        │
│ • 以__开头的是内部标签                      │
└─────────────────────────────────────────────┘

指标命名结构：

┌─────────────────────────────────────────────┐
│ 命名组成                                    │
├─────────────────────────────────────────────┤
│ [命名空间]_[子系统]_[名称]_[后缀]           │
└─────────────────────────────────────────────┘

示例：
┌─────────────────────────────────────────────┐
│ http_requests_total                         │
│ └──┬──┘ └───┬───┘ └──┬──┘                   │
│   │       │       │                         │
│ 命名空间  名称    后缀                       │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ node_memory_MemAvailable_bytes              │
│ └──┬──┘ └───┬───┘ └────────┬─────────┘      │
│   │       │           │                     │
│ 命名空间  子系统      名称_后缀              │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ process_cpu_seconds_total                   │
│ └─────┬─────┘ └──┬──┘ └───┬───┘             │
│       │         │        │                   │
│    命名空间    名称     后缀                 │
└─────────────────────────────────────────────┘

常见命名空间：

┌─────────────────────────────────────────────┐
│ 系统级命名空间                              │
├─────────────────────────────────────────────┤
│ node_       # 主机监控                      │
│ process_    # 进程监控                      │
│ prometheus_ # Prometheus自身                │
│ go_         # Go运行时                      │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ 应用级命名空间                              │
├─────────────────────────────────────────────┤
│ http_       # HTTP相关                      │
│ api_        # API相关                       │
│ db_         # 数据库相关                    │
│ cache_      # 缓存相关                      │
│ queue_      # 队列相关                      │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ 服务级命名空间                              │
├─────────────────────────────────────────────┤
│ mysql_      # MySQL                         │
│ redis_      # Redis                         │
│ nginx_      # Nginx                         │
│ kafka_      # Kafka                         │
└─────────────────────────────────────────────┘

类型后缀：

┌─────────────────────────────────────────────┐
│ Counter后缀                                 │
├─────────────────────────────────────────────┤
│ _total      # 累积总数（推荐）              │
│                                             │
│ 示例：                                      │
│ http_requests_total                         │
│ http_errors_total                           │
│ tasks_completed_total                       │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ Gauge后缀                                   │
├─────────────────────────────────────────────┤
│ 无特定后缀，但可添加状态后缀                │
│                                             │
│ 示例：                                      │
│ node_memory_MemAvailable_bytes              │
│ queue_length                                │
│ active_connections                          │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ Histogram/Summary后缀                       │
├─────────────────────────────────────────────┤
│ 无特定后缀，但会自动生成：                  │
│ _bucket    # Histogram桶                    │
│ _sum       # 总和                           │
│ _count     # 总数                           │
│                                             │
│ 示例：                                      │
│ http_request_duration_seconds               │
│   ├── http_request_duration_seconds_bucket  │
│   ├── http_request_duration_seconds_sum     │
│   └── http_request_duration_seconds_count   │
└─────────────────────────────────────────────┘

单位后缀规范：

┌─────────────────────────────────────────────┐
│ 时间单位                                    │
├─────────────────────────────────────────────┤
│ _seconds    # 秒（推荐）                    │
│ _milliseconds # 毫秒                        │
│ _minutes    # 分钟                          │
│ _hours      # 小时                          │
│                                             │
│ 示例：                                      │
│ http_request_duration_seconds               │
│ task_processing_time_seconds                │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ 数据大小单位                                │
├─────────────────────────────────────────────┤
│ _bytes      # 字节（推荐）                  │
│ _kilobytes  # 千字节                        │
│ _megabytes  # 兆字节                        │
│ _gigabytes  # 吉字节                        │
│                                             │
│ 示例：                                      │
│ http_response_size_bytes                    │
│ node_memory_MemTotal_bytes                  │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ 比例单位                                    │
├─────────────────────────────────────────────┤
│ _ratio      # 比率（0-1）                   │
│ _percent    # 百分比（0-100）               │
│                                             │
│ 示例：                                      │
│ cache_hit_ratio                             │
│ cpu_usage_percent                           │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ 计数单位                                    │
├─────────────────────────────────────────────┤
│ 无后缀或_total                              │
│                                             │
│ 示例：                                      │
│ http_requests_total                         │
│ queue_length                                │
│ active_connections                          │
└─────────────────────────────────────────────┘

好的命名示例：

# HTTP相关
http_requests_total                 # HTTP请求总数
http_request_duration_seconds       # HTTP请求延迟
http_response_size_bytes            # HTTP响应大小
http_errors_total                   # HTTP错误总数

# 数据库相关
db_query_duration_seconds           # 数据库查询延迟
db_connections_active               # 活跃数据库连接
db_query_errors_total               # 数据库查询错误

# 缓存相关
cache_hits_total                    # 缓存命中数
cache_misses_total                  # 缓存未命中数
cache_evictions_total               # 缓存驱逐数

# 队列相关
queue_messages_total                # 队列消息数
queue_processing_duration_seconds   # 队列处理延迟
queue_errors_total                  # 队列错误数

# 系统相关
node_cpu_seconds_total              # CPU使用时间
node_memory_MemAvailable_bytes      # 可用内存
node_filesystem_size_bytes          # 文件系统大小

不好的命名示例：

# 不推荐：使用驼峰命名
httpRequestsTotal
httpRequestDuration

# 不推荐：缺少单位
http_request_duration
node_memory_available

# 不推荐：使用count而非total
http_requests_count

# 不推荐：含义不清
metric1
data
value

# 不推荐：单位不一致
http_request_time_ms
node_memory_available_kb

标签命名原则：

┌─────────────────────────────────────────────┐
│ 1. 使用snake_case                           │
├─────────────────────────────────────────────┤
│ 好的：method, status_code, request_id       │
│ 不好的：Method, statusCode, requestID       │
├─────────────────────────────────────────────┤
│ 2. 名称要有意义                             │
├─────────────────────────────────────────────┤
│ 好的：method, endpoint, status              │
│ 不好的：m, e, s                             │
├─────────────────────────────────────────────┤
│ 3. 保持一致性                               │
├─────────────────────────────────────────────┤
│ 好的：所有地方都用service                   │
│ 不好的：有的用service，有的用app            │
├─────────────────────────────────────────────┤
│ 4. 避免冗余                                 │
├─────────────────────────────────────────────┤
│ 好的：status                                │
│ 不好的：http_status                         │
└─────────────────────────────────────────────┘

常用标签名：

┌─────────────────────────────────────────────┐
│ HTTP相关标签                                │
├─────────────────────────────────────────────┤
│ method        # HTTP方法                    │
│ status        # HTTP状态码                  │
│ endpoint      # API端点                     │
│ path          # 请求路径                    │
│ host          # 主机名                      │
│ scheme        # 协议                        │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ 服务相关标签                                │
├─────────────────────────────────────────────┤
│ service       # 服务名称                    │
│ version       # 服务版本                    │
│ environment   # 环境                        │
│ region        # 区域                        │
│ zone          # 可用区                      │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┤
│ 数据库相关标签                              │
├─────────────────────────────────────────────┤
│ db            # 数据库名                    │
│ table         # 表名                        │
│ operation     # 操作类型                    │
│ query_type    # 查询类型                    │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┤
│ 缓存相关标签                                │
├─────────────────────────────────────────────┤
│ cache         # 缓存名称                    │
│ key           # 缓存键（注意基数）          │
│ result        # 结果（hit/miss）            │
└─────────────────────────────────────────────┘

标签值规范：

┌─────────────────────────────────────────────┐
│ 1. 使用小写                                 │
├─────────────────────────────────────────────┤
│ 好的：method="get", status="200"            │
│ 不好的：method="GET", status="200"          │
├─────────────────────────────────────────────┤
│ 2. 使用snake_case或kebab-case               │
├─────────────────────────────────────────────┤
│ 好的：service="user-service"                │
│ 不好的：service="UserService"               │
├─────────────────────────────────────────────┤
│ 3. 避免空格和特殊字符                       │
├─────────────────────────────────────────────┤
│ 好的：endpoint="/api/users"                 │
│ 不好的：endpoint="/api/users list"          │
├─────────────────────────────────────────────┤
│ 4. 保持格式一致                             │
├─────────────────────────────────────────────┤
│ 好的：status="200", status="404"            │
│ 不好的：status="200", status="Not Found"    │
└─────────────────────────────────────────────┘

# HTTP服务指标命名示例

# 请求计数
http_requests_total{
    method="get",
    endpoint="/api/users",
    status="200",
    service="user-service",
    environment="production"
}

# 请求延迟
http_request_duration_seconds{
    method="get",
    endpoint="/api/users",
    status="200",
    service="user-service"
}

# 响应大小
http_response_size_bytes{
    method="get",
    endpoint="/api/users",
    status="200",
    service="user-service"
}

# 活跃连接数
http_active_connections{
    service="user-service",
    environment="production"
}

# 数据库指标命名示例

# 查询延迟
db_query_duration_seconds{
    db="mysql",
    operation="select",
    table="users",
    service="user-service"
}

# 连接数
db_connections_active{
    db="mysql",
    service="user-service"
}

# 查询错误
db_query_errors_total{
    db="mysql",
    operation="select",
    error_type="timeout",
    service="user-service"
}

# 慢查询数
db_slow_queries_total{
    db="mysql",
    service="user-service"
}

# 缓存指标命名示例

# 缓存操作
cache_operations_total{
    cache="redis",
    operation="get",
    result="hit",
    service="user-service"
}

# 缓存延迟
cache_operation_duration_seconds{
    cache="redis",
    operation="get",
    service="user-service"
}

# 缓存大小
cache_memory_usage_bytes{
    cache="redis",
    service="user-service"
}

# 缓存键数量
cache_keys_total{
    cache="redis",
    service="user-service"
}

指标命名检查清单：

□ 使用snake_case命名
□ 以字母开头
□ 包含适当的命名空间
□ 包含正确的单位后缀
□ Counter使用_total后缀
□ 名称有明确含义
□ 名称简洁但不模糊
□ 与现有指标命名风格一致

标签命名检查清单：

□ 使用snake_case命名
□ 名称有明确含义
□ 标签值是有限集合
□ 标签值格式一致
□ 使用小写字母
□ 避免冗余信息
□ 与现有标签命名风格一致