📚 课程目录第2章 Prometheus指标基础

2. Prometheus 指标基础：核心指标类型及其在证书监控中的应用

在构建证书轮换调度器的监控体系之前，必须深入理解 Prometheus 的四种核心指标类型。每种类型对应不同的数据语义和聚合方式，选错类型将直接导致告警阈值失效或调度决策偏差。本节将逐一剖析 Counter、Gauge、Histogram 和 Summary，并给出它们在证书生命周期管理中的典型应用场景。

2.1 核心指标类型对比总览

指标类型	数据语义	典型值特征	聚合操作	证书监控适用场景
Counter	只增不减的累计值（重启可重置）	单调递增	`rate()` / `increase()`	证书轮换次数、失败次数、API 调用量
Gauge	可增可减的瞬时快照	上下波动	`avg()` / `max()` / `min()`	证书剩余天数、当前有效证书数、轮换队列深度
Histogram	观测值分布 + 计数 + 总和	分桶统计	`histogram_quantile()`	证书轮换耗时分布、API 响应延迟分布
Summary	预计算分位数 + 计数 + 总和	客户端侧分位数	直接读取 `quantile` 标签	证书签发延迟的 P99 监控（需精确分位数）

选型原则： 能累加且只关心速率 → Counter；关心当前状态 → Gauge；需要分析分布 → Histogram 或 Summary。证书轮换调度器中最常用的是 Gauge（剩余有效期）和 Counter（轮换事件计数）。

2.2 Counter：事件计数与速率计算

Counter 是最基础的累计型指标，适合记录证书轮换调度器中的各类事件总量。由于 Counter 只增不减，直接查看原始值意义不大，必须配合 rate() 或 increase() 函数计算每秒增量或一段时间内的增长量。

# 证书轮换成功次数（Counter）
cert_rotation_total{status="success"} 1287

# 证书轮换失败次数（Counter）
cert_rotation_total{status="failure"} 23

# 查询最近 5 分钟平均每秒轮换速率
rate(cert_rotation_total{status="success"}[5m])

# 查询最近 1 小时轮换失败增长量
increase(cert_rotation_total{status="failure"}[1h])

  证书监控应用： 使用 Counter 记录每次证书轮换操作，结合 rate() 发现异常突增（如轮换风暴）或突降（如调度器挂起）。告警规则示例：rate(cert_rotation_total{status="failure"}[5m]) > 0.1 表示每分钟失败超过 0.1 次即告警。

2.3 Gauge：瞬时状态与阈值告警

Gauge 是证书监控中使用频率最高的指标类型。证书剩余有效期、证书是否即将过期、当前待轮换证书数量等状态信息，都适合用 Gauge 表达。Gauge 支持任意加减操作，可以直接设置告警阈值。

# 证书剩余有效期（天）（Gauge）
cert_days_remaining{cn="api.example.com",issuer="Let's Encrypt"} 14.3

# 当前待轮换证书数量（Gauge）
cert_pending_rotation_count 5

# 证书是否已过期（1=过期，0=未过期）（Gauge）
cert_expired{cn="db.internal"} 0

注意： Gauge 的告警阈值必须结合证书轮换策略设定。例如，如果调度器在剩余 30 天时开始轮换，则 cert_days_remaining < 30 应触发“即将轮换”信息，cert_days_remaining < 7 触发“紧急”告警。避免将阈值设得过于接近过期时间，防止因网络延迟或重试导致证书真正过期。

2.4 Histogram：轮换耗时分布与分位数计算

Histogram 将观测值（如证书轮换耗时）分配到预定义的桶（bucket）中，同时记录总计数和总和。通过 histogram_quantile() 函数可以计算分位数，用于分析轮换操作的性能分布。

# 证书轮换耗时分布（Histogram）
cert_rotation_duration_seconds_bucket{le="0.5"} 120
cert_rotation_duration_seconds_bucket{le="1.0"} 450
cert_rotation_duration_seconds_bucket{le="2.0"} 680
cert_rotation_duration_seconds_bucket{le="5.0"} 720
cert_rotation_duration_seconds_bucket{le="+Inf"} 730
cert_rotation_duration_seconds_sum 892.5
cert_rotation_duration_seconds_count 730

# 计算 P95 轮换耗时（最近 10 分钟）
histogram_quantile(0.95, rate(cert_rotation_duration_seconds_bucket[10m]))

桶设计建议： 证书轮换通常涉及网络请求和证书存储写入，耗时一般在 0.5s~5s 之间。桶边界建议设置为 [0.1, 0.5, 1.0, 2.0, 5.0, 10.0, +Inf]，覆盖正常和异常场景。桶太粗会丢失精度，太细则增加存储开销。

2.5 Summary：客户端预计算分位数

Summary 与 Histogram 类似，但分位数在客户端侧预计算，直接暴露为带有 quantile 标签的指标。Summary 不依赖 Prometheus 服务端的分位数计算，适合对分位数精度要求极高且已知分位数范围的场景。

# 证书签发延迟 Summary（客户端预计算 P50/P90/P99）
cert_signing_latency_seconds{quantile="0.5"} 0.32
cert_signing_latency_seconds{quantile="0.9"} 0.87
cert_signing_latency_seconds{quantile="0.99"} 2.15
cert_signing_latency_seconds_sum 2340.6
cert_signing_latency_seconds_count 3200

  Histogram vs Summary 选择：
  如果需要在告警规则中动态调整分位数（如从 P95 改为 P99），使用 Histogram。
如果分位数固定且需要精确聚合（如多个实例合并后仍保持精度），使用 Summary。
证书轮换调度器推荐使用 Histogram，因为轮换耗时分布可能随证书数量变化，需要灵活调整分位数。

2.6 证书监控指标类型选择决策流程

2.7 证书监控指标定义最佳实践

命名规范： 使用 cert_ 作为前缀，例如 cert_days_remaining、cert_rotation_duration_seconds。单位（如 _seconds、_total）必须遵循 Prometheus 命名约定。
标签设计： 至少包含 cn（通用名称）、issuer（签发机构）、status（成功/失败）。避免标签基数过高（如将序列号作为标签）。
单位统一： 时间相关指标统一使用秒（seconds），有效期使用天（days），避免单位混用导致计算错误。
Histogram 桶边界： 根据实际观测数据调整，初始可参考 [0.1, 0.5, 1, 2, 5, 10, +Inf]，运行一周后根据真实分布优化。

  实战检查清单：
  所有轮换事件是否已用 Counter 记录？
证书剩余有效期是否用 Gauge 暴露？
轮换耗时是否用 Histogram 采集？
标签是否包含 cn 和 issuer？
是否已设置 cert_days_remaining < 30 的告警规则？