📚 课程目录第4章配置缓存命中巡检的意义

4. 缓存命中率指标：Prometheus 指标暴露与关键解读

Kyverno 内置了 Prometheus 指标端点，用于暴露策略引擎内部缓存的运行状态。通过监控 kyverno_cache_hits_total 和 kyverno_cache_misses_total 两个核心计数器，运维人员可以精确评估配置缓存的效率，并快速定位缓存失效或未命中的根因。

4.1 指标暴露机制

Kyverno 默认在 :8000 端口上提供 /metrics 端点。Prometheus 可以通过标准的 ServiceMonitor 或 PodMonitor 自动发现并采集这些指标。

  关键配置检查点： 确保 Prometheus 的采集目标中包含了 Kyverno Pod 的 8000 端口，并且 ServiceMonitor 的 matchLabels 与 Kyverno Service 的标签匹配。

# 验证指标端点是否正常暴露
kubectl port-forward -n kyverno svc/kyverno-svc 8000:8000
curl -s http://localhost:8000/metrics | grep kyverno_cache

4.2 核心指标解读

下表列出了与缓存命中率直接相关的两个 Prometheus 计数器指标及其语义：

指标名称	类型	标签（Labels）	含义
`kyverno_cache_hits_total`	Counter	`resource_kind`, `cache_type`	从 Kyverno 配置缓存中成功获取数据的累计次数。每次策略引擎查询缓存并命中时，该计数器递增。
`kyverno_cache_misses_total`	Counter	`resource_kind`, `cache_type`	查询缓存但未找到所需数据的累计次数。每次缓存未命中时，该计数器递增，通常意味着需要回源到 API Server 获取数据。

标签说明： resource_kind 表示被缓存的资源类型（如 Namespace、ConfigMap、ClusterPolicy）；cache_type 表示缓存层级（如 lru 表示 LRU 缓存，informer 表示 Informer 本地缓存）。

4.3 命中率计算公式

缓存命中率是衡量缓存有效性的核心指标。计算公式基于一段时间窗口内的累计计数器差值：

缓存命中率 = (Hits) / (Hits + Misses) × 100%

其中：
  Hits   = increase(kyverno_cache_hits_total[5m])
  Misses = increase(kyverno_cache_misses_total[5m])

在 PromQL 中，完整的查询语句如下：

# 按资源类型和缓存类型分组计算 5 分钟内的命中率
(
  sum(increase(kyverno_cache_hits_total[5m])) by (resource_kind, cache_type)
  /
  (
    sum(increase(kyverno_cache_hits_total[5m])) by (resource_kind, cache_type)
    +
    sum(increase(kyverno_cache_misses_total[5m])) by (resource_kind, cache_type)
  )
) * 100

4.4 缓存命中率指标架构

下图展示了 Kyverno 缓存命中率指标的采集、计算与告警链路：

4.5 命中率阈值与故障判定

根据生产环境经验，缓存命中率的不同区间对应不同的健康状态：

命中率区间	健康状态	可能原因	建议操作
≥ 95%	健康	缓存工作正常，策略引擎高效运行	无需干预，持续监控
80% – 95%	亚健康	部分缓存未命中，可能因缓存容量不足或 TTL 过短	检查缓存大小配置，考虑增加 LRU 缓存条目数
60% – 80%	警告	频繁回源 API Server，可能因缓存频繁失效或资源频繁变更	排查资源变更频率，检查 Informer 重新同步间隔
< 60%	严重	缓存几乎失效，策略引擎性能严重下降	立即检查 Kyverno 日志，确认缓存组件是否异常重启

常见误区： 不要仅看全局命中率。务必按 resource_kind 和 cache_type 维度拆分查看。例如，Namespace 缓存命中率可能很高，但 ConfigMap 缓存命中率可能很低，这会导致全局指标掩盖局部问题。

4.6 实战：在 Grafana 中配置命中率面板

以下是一个可直接用于 Grafana 面板的 PromQL 查询，按资源类型展示命中率：

# 按 resource_kind 分组，计算 5 分钟平均命中率
(
  sum(increase(kyverno_cache_hits_total[5m])) by (resource_kind)
  /
  (
    sum(increase(kyverno_cache_hits_total[5m])) by (resource_kind)
    +
    sum(increase(kyverno_cache_misses_total[5m])) by (resource_kind)
  )
) * 100

建议在 Grafana 中设置以下告警规则：

Warning 告警： 当任意 resource_kind 的命中率低于 90% 且持续 5 分钟时触发。
Critical 告警： 当任意 resource_kind 的命中率低于 70% 且持续 5 分钟时触发。
通知渠道： 建议通过 Alertmanager 发送到即时通讯工具（如 Slack、钉钉）或 PagerDuty。