📚 课程目录第4章误差预算台账核心字段设计

4. 误差预算台账核心字段设计

误差预算台账是 SLO 管理的数据核心，其字段设计直接决定了预算计算、消耗追踪与告警触发的准确性和可维护性。本章从 时间窗口、SLI 值、SLO 目标、预算消耗量 和 剩余预算 五个维度，给出 Metric Design 视角下的字段定义、类型选择与约束规则。

4.1 时间窗口字段

时间窗口定义了误差预算的统计周期，是台账记录的“时间锚点”。常见窗口类型包括滚动窗口（Sliding Window）与日历窗口（Calendar Window）。

字段名	类型	说明	示例值
`window_start`	timestamp	窗口起始时间（含）	2025-04-01 00:00:00 UTC
`window_end`	timestamp	窗口结束时间（不含）	2025-04-08 00:00:00 UTC
`window_type`	enum	窗口类型：rolling / calendar	rolling
`window_duration`	interval	窗口长度，如 7d、30d	7 days

设计要点：滚动窗口适合实时监控场景，每次计算基于最近 N 天数据；日历窗口适合财务或合规审计场景，按自然月/季度对齐。建议台账同时保留 window_start 与 window_end，避免仅存时长导致跨时区歧义。

4.2 SLI 值字段

SLI（Service Level Indicator）值是误差预算计算的原始输入，通常为一段时间内的成功率、延迟达标率或可用时长占比。

字段名	类型	说明	示例值
`sli_value`	float	SLI 实际值，范围 [0.0, 1.0]	0.9987
`sli_unit`	string	SLI 单位，如 ratio、ms、seconds	ratio
`good_events`	bigint	成功事件计数（可选）	998700
`total_events`	bigint	总事件计数（可选）	1000000

精度警告：SLI 值建议使用 float64 或 decimal(18,6)，避免因浮点舍入导致预算计算偏差。当 SLI 接近 1.0（如 0.99999）时，微小误差会被预算公式放大。

4.3 SLO 目标字段

SLO 目标定义了服务承诺的阈值，是误差预算的“基准线”。该字段通常与 SLI 值成对出现，用于计算偏差。

字段名	类型	说明	示例值
`slo_target`	float	SLO 目标值，范围 [0.0, 1.0]	0.9990
`slo_compliance`	enum	合规类型：monthly / quarterly	monthly
`budget_period`	interval	预算重置周期	30 days

  关键约束：slo_target 必须大于等于 SLI 值的历史最低容忍线。例如，SLO 为 99.9% 时，SLI 低于 99.9% 即开始消耗预算。目标值一旦设定，不建议频繁修改，否则台账历史记录将失去可比性。

4.4 预算消耗量字段

预算消耗量表示在时间窗口内，因 SLI 未达标而“消耗”的误差预算比例。计算公式为：budget_consumed = max(0, slo_target - sli_value) * window_duration_seconds。

字段名	类型	说明	示例值
`budget_consumed`	float	当前窗口消耗的预算量（秒或百分比）	86.4
`budget_consumed_unit`	string	消耗单位：seconds / percent	seconds
`consumed_rate`	float	消耗速率，单位时间消耗量	12.34

单位选择：推荐使用 seconds 作为消耗单位，便于与 SLO 目标中的时间窗口对齐。百分比单位在跨窗口对比时容易产生歧义，例如 10% 消耗在 7 天窗口与 30 天窗口中的实际含义不同。

4.5 剩余预算字段

剩余预算反映当前窗口内还可容忍的故障时间，是告警与决策的直接依据。

字段名	类型	说明	示例值
`budget_remaining`	float	剩余预算量（秒或百分比）	518.4
`budget_remaining_pct`	float	剩余预算百分比	85.7
`burn_rate`	float	当前燃烧速率，与消耗速率对应	0.8
`eta_exhaustion`	timestamp	预计预算耗尽时间	2025-04-05 14:30:00 UTC

告警阈值：当 budget_remaining_pct 低于 20% 时，应触发黄色告警；低于 5% 时触发红色告警。同时监控 burn_rate，若 burn_rate > 1.0 且持续超过 1 小时，说明故障正在加速消耗预算，需立即响应。

4.6 核心字段关系图

下图展示了五个核心字段在误差预算台账中的流转关系：时间窗口定义计算范围，SLI 值与 SLO 目标共同决定预算消耗量，消耗量累积后得出剩余预算，剩余预算再驱动告警与燃烧速率分析。

4.7 字段设计检查清单

在落地台账表结构时，建议逐项核对以下要点：

时间窗口唯一性：同一 SLO 在同一时间窗口内只能有一条记录，使用 (slo_id, window_start, window_type) 作为联合唯一键。
SLI 值范围约束：添加 CHECK 约束 sli_value BETWEEN 0 AND 1，防止脏数据导致预算计算异常。
SLO 目标不可为空：每个台账记录必须关联有效的 SLO 目标，建议使用外键引用 SLO 配置表。
预算消耗量非负：消耗量字段必须大于等于 0，可通过应用层或数据库触发器保证。
剩余预算实时性：剩余预算字段应随新窗口数据写入而更新，避免使用定时批处理导致延迟。

  最佳实践：将 budget_remaining_pct 与 burn_rate 作为派生字段，通过视图或物化视图计算，减少冗余存储。但 budget_consumed 建议持久化，因为它是审计与复盘的核心依据。