slo-architect

SLO 架构师

定义真正有意义的 SLO。现实中大多数“SLO”都是没人相信的随意数字——每个端点都设为 99.9%，没有 SLI 定义、没有错误预算，也没有预算消耗时的处理策略。这项技能贯彻 Google SRE Workbook 中的纪律：选择合适的 SLI，设定用户真正关心的目标，计算错误预算，配置多窗口消耗速率告警，并制定预算耗尽时的书面策略。

适用场景

• 为服务或功能定义新的 SLO
• 检查现有 SLO 中的常见问题
• 选择合适的 SLI（基于事件、时间窗口或请求）
• 计算错误预算和消耗速率告警阈值
• 将 SLO 与现有控制措施关联——功能标志中止、混沌工程爆炸半径、操作员能力等级

不适用场景

• 通用可观测性策略（指标 + 日志 + 跟踪）→ 使用 observability-designer
• 具有法律约束力、面向客户的 SLA → 这是合同起草，而非工程工作
• 性能负载测试（关注容量，而非可靠性）→ 使用 performance-profiler
• 正在进行的事件响应 → 使用 incident-response

核心原则：SLO 是对用户体验的承诺

SLI  ⟶  measurable signal of user-perceived health (e.g., HTTP 2xx rate)
SLO  ⟶  target for the SLI over a window (e.g., 99.9% over 30 days)
SLA  ⟶  customer-facing commitment with consequences (separate concern)
EB   ⟶  error budget: 100% − SLO target = how much "bad" you can spend
BR   ⟶  burn rate: how fast you're consuming the error budget

四种常见的致命错误：

1. 目标过高（对无法达到该目标的服务要求 99.99% 以上）——任何小故障都会违反 SLO；告警会沦为噪声。
2. SLI 错误（用 CPU 使用率代替用户体验）——系统可能显示“正常”，用户却在受苦。
3. 没有错误预算策略——如果没有约定好的应对措施，预算消耗就毫无意义。
4. 单窗口消耗速率告警——要么噪声太多（5 分钟的峰值就触发页面告警），要么响应太慢（预算耗尽后才发现）。

下面的 3 个工具可以发现这些问题。

快速开始

SKILL=engineering/slo-architect/skills/slo-architect

# 1. Design an SLO
python "$SKILL/scripts/slo_designer.py" \
  --service checkout-svc \
  --sli-type request-success-rate \
  --target 99.9 \
  --window-days 30

# 2. Compute error budget + multi-window burn-rate alerts
python "$SKILL/scripts/error_budget_calculator.py" \
  --target 99.9 --window-days 30

# 3. Review existing SLO definitions for common bugs
python "$SKILL/scripts/slo_review.py" --slo-doc docs/slos/

3 个 Python 工具

均仅使用标准库。

slo_designer.py

生成包含必填字段的结构化 SLO 定义。缺少任何必填字段时会拒绝生成（exit 1）。

python scripts/slo_designer.py \
  --service checkout-svc \
  --sli-type request-success-rate \
  --target 99.9 \
  --window-days 30 \
  --owner team-checkout

支持的 SLI 类型：

• request-success-rate — (total_requests - bad_requests) / total_requests
• request-latency — count(requests < threshold) / total_requests
• availability-time — (window - downtime) / window
• data-freshness — count(data_age < threshold) / total_data_points
• correctness — count(correct_outputs) / total_outputs

默认输出为 markdown，其中所有必填字段都已填写或标记为 <must define>。JSON 输出（--format json）可供 slo_review.py 使用。

error_budget_calculator.py

根据目标可用性和时间窗口，计算：

• 窗口内允许的停机时间
• 符合 Google SRE Workbook（第 5 章）要求的多窗口消耗速率阈值：
  • 快速消耗——如果 1 小时内消耗了月度预算的 2%，则触发页面告警
  • 缓慢消耗——如果 6 小时内消耗了 10%，则触发页面告警；如果 3 天内消耗了 10%，则创建工单
• 推荐的告警规则（PromQL 格式输出）

python scripts/error_budget_calculator.py --target 99.9 --window-days 30
python scripts/error_budget_calculator.py --target 99.95 --window-days 7 --format json

slo_review.py

检查目录中的 SLO 定义（markdown 或 JSON），查找常见问题。

python scripts/slo_review.py --slo-doc docs/slos/

检查项：

• target_too_high：目标 ≥ 99.99%（只有投入大量工程资源才能持续实现）
• target_too_low：目标 ≤ 99.0%（SLI 可能选错了；用户会察觉）
• window_too_short：窗口 < 7 天（统计噪声占主导）
• window_too_long：窗口 > 90 天（反馈太慢）
• no_sli_definition：缺少 SLI 部分或定义含糊（“一切正常”）
• no_error_budget_policy：没有记录预算消耗时的应对措施
• cpu_as_sli：将 CPU/内存作为用户体验的替代指标（信号错误）

SLI 选择速查表

用户体验	SLI 类型	衡量内容
“请求是否成功？”	request-success-rate	2xx / total
“响应是否足够快？”	request-latency	count(p99 < threshold) / total
“服务是否正常运行？”	availability-time	(window - downtime) / window
“数据是否是最新的？”	data-freshness	count(data_age < threshold) / total
“答案是否正确？”	correctness	count(correct) / total

示例和反模式请参阅 references/sli_design.md。

错误预算计算（基础知识）

对于为期 30 天、目标为 99.9% 的 SLO：

• 允许的不可用时间：0.1% × 30 × 24 × 60 = 43.2 minutes
• 1 小时快速消耗阈值（消耗月度预算的 2%）：2% × 43.2 / 60 ≈ 1.44 ratio multiplier
• 6 小时缓慢消耗阈值（6 小时内消耗 10%）：10% × 43.2 / 360 ≈ 0.6 ratio multiplier

error_budget_calculator.py 会为你完成这些计算，并生成可直接粘贴的告警规则。

与其他技能组合使用

此技能明确与另外三项技能组合使用：

技能	组合方式
feature-flags-architect	发布中止标准会参考 SLO 消耗率阈值
chaos-engineering	爆炸半径计算器已将月度错误预算作为输入——在此处定义
kubernetes-operator	Operator 能力 L4（深度洞察）要求配置 SLO 和 Prometheus 规则

error_budget_calculator.py 的输出格式与 engineering/skills/chaos-engineering/scripts/blast_radius_calculator.py 通过 stdin 接收的格式一致。

工作流

工作流 1：定义新的 SLO

1. Pick the user journey to protect (e.g., "checkout completion").
2. Choose SLI type (request-success-rate, latency, availability, freshness, correctness).
3. Define the SLI precisely: numerator/denominator with concrete labels.
4. Pick a target by measuring 30 days of historical SLI value:
     target = floor(p50 of last 30 days × 100) / 100
   This avoids targets the system has never sustained.
5. Pick a window (28 days = 4 calendar weeks, recommended).
6. Run slo_designer.py to render the SLO definition.
7. Run error_budget_calculator.py to get burn-rate alerts.
8. Write the error budget policy (what happens when budget burns).
9. Run slo_review.py — must pass before the SLO is "live".

工作流 2：每季度审查 SLO

1. For every active SLO, run slo_review.py — fix any FAIL findings.
2. Look at last quarter's data:
   - Was the SLO too easy (never burned budget)? Tighten target.
   - Was it too hard (frequently burned)? Loosen target OR fix the system.
   - Did burn-rate alerts fire usefully (not too noisy, not too late)? Adjust thresholds.
3. Audit error budget policies — were they actually followed when budget burned?
4. Commit revised SLOs; archive old versions with date stamps.

工作流 3：由 SLO 驱动回滚

1. New deploy starts burning error budget faster than baseline.
2. Burn-rate alert fires (from error_budget_calculator.py thresholds).
3. Auto-rollback via feature flag (kill switch from feature-flags-architect).
4. Postmortem feeds into next SLO revision.

参考资料

• references/slo_principles.md — SLI、SLO 与 SLA 的区别，Google SRE Workbook 规范
• references/sli_design.md — 如何选择合适的 SLI；5 种类型及示例
• references/error_budget.md — 错误预算计算、消耗率告警、预算策略
• references/composition.md — SLO 如何影响功能开关、混沌工程和 Operator

斜杠命令

/slo-design — 交互式 SLO 设计向导，可运行全部 3 个工具。

资源模板

• assets/slo_template.yaml — 可填写的 SLO YAML
• assets/error_budget_policy.md — 可填写的策略模板

反模式

• 每个端点都设置 99.99% — 复制粘贴的 SLO，无人验证系统是否能达到目标
• 将 CPU 使用率作为 SLI — 系统指标并不代表用户体验
• 仅使用单时间窗口的消耗率告警 — 5 分钟窗口过于嘈杂，30 天窗口又太慢
• 没有错误预算策略 — 如果没有相应行动，预算消耗就毫无意义
• SLO 没有负责人 — 无人负责，最终会逐渐失效
• 一年只审查一次 SLO — 系统特征变化得比这快
• 在 SLO 文档中写入 SLA — 受众不同，利害关系也不同；应分开处理
• SLO 目标 = SLA 目标 — SLO 必须更严格（应在客户察觉之前就达到优于合同要求的水平）

可验证的成功标准

使用此技能的团队应达到以下目标：

• 100% 的 SLO 通过 slo_review.py，且 FAIL 结果为 0
• 每个 SLO 都有记录在案的负责人、错误预算、消耗率告警和策略
• 每个触发的 SLO 每月消耗率告警触发次数 ≤2（传递信号，而非噪声）
• 检测到 SLO 违规的平均时间：<30 min（多时间窗口消耗率告警正常工作）
• 每季度都进行 SLO 审查（而非每年）