4. 命中率定义与计算：命中率公式推导、有效匹配请求与总请求的统计口径、采样窗口设置

API Priority 策略的命中率是衡量 Operator 控制面中请求优先级调度有效性的核心指标。错误的命中率定义会导致误报率飙升，掩盖真实的调度瓶颈。本节从公式推导出发，严格定义统计口径与采样窗口，确保审计与 SRE 复盘时数据口径一致。

4.1 命中率公式推导

在 Kubernetes API Server 的 Priority & Fairness 机制中，一个请求被“命中”意味着它成功匹配了某个 FlowSchema，并被分配到了对应的 PriorityLevel。命中率的基本公式为：

命中率 (Hit Rate) = (有效匹配请求数) / (总请求数) × 100%

但实际审计中需要区分“严格命中”与“宽松命中”：

推导后的完整公式：

HitRate_strict = (Σ matched_expected_flows) / (Σ total_requests) × 100%
HitRate_loose  = (Σ matched_any_flows) / (Σ total_requests) × 100%

其中 matched_expected_flows 仅统计与 Operator 预定义的 FlowSchema 名称匹配的请求，排除 catch-all 与默认流控规则。

4.2 有效匹配请求与总请求的统计口径

统计口径不一致是导致命中率计算偏差的首要原因。以下表格列出必须统一的口径维度：

4.3 采样窗口设置

采样窗口直接影响命中率的波动性与审计结论的可靠性。窗口过短会导致抖动，过长会掩盖瞬时故障。

推荐的三级采样窗口策略：

• 实时窗口（1 分钟）：用于告警与异常检测，容忍 5% 的抖动。
• 短时窗口（5 分钟）：用于 Operator 控制面健康度仪表盘，要求命中率 ≥ 95%。
• 审计窗口（1 小时）：用于合规复盘与误报分析，要求严格命中率 ≥ 99%。

窗口设置对比：

4.4 命中率计算流程（SVG）

下图展示了从原始请求到命中率输出的完整计算流水线，包含统计口径过滤与采样窗口聚合：

4.5 误报复核中的命中率阈值

在 Operator 控制面审计中，命中率低于阈值时触发误报。以下是基于生产环境经验总结的推荐阈值：

• 严格命中率 < 95%：触发黄色告警，提示可能存在 FlowSchema 配置遗漏或请求来源异常。
• 严格命中率 < 90%：触发红色告警，需要立即复核 Operator 的 FlowSchema 与 PriorityLevel 配置。
• 宽松命中率 < 99%：表示有请求未被任何 FlowSchema 匹配，可能落入默认队列，影响调度公平性。

4.6 采样窗口与命中率关系（SVG）

下图展示了不同采样窗口下命中率的波动特征，帮助 SRE 工程师选择合适的窗口配置：

4.7 命中率计算代码示例

以下 PromQL 查询示例展示了如何在 Prometheus 中计算严格命中率，并应用 5 分钟采样窗口：

# 严格命中率（5分钟窗口）
(
  sum(
    rate(
      apiserver_flowcontrol_request_execution_seconds_count{
        flow_schema=~"operator-.*",
        flow_schema!~".*catch-all.*"
      }[5m]
    )
  )
  /
  sum(
    rate(
      apiserver_flowcontrol_request_execution_seconds_count[5m]
    )
  )
) * 100

审计脚本中建议同时输出严格与宽松命中率，便于对比分析：

# 宽松命中率（5分钟窗口）
(
  sum(
    rate(
      apiserver_flowcontrol_request_execution_seconds_count[5m]
    )
  )
  /
  sum(
    rate(
      apiserver_flowcontrol_request_execution_seconds_count[5m]
    )
  )
) * 100
# 宽松命中率始终为 100%，用于验证分母一致性