observability-designer

可观测性设计师

设计可用于生产环境的可观测性策略，将三大支柱（指标、日志、追踪）与 SLI/SLO 框架、黄金信号监控、多窗口消耗速率告警以及告警噪声优化相结合。

核心能力

• SLI/SLO 框架 — 从黄金信号中选择 SLI，将其映射到 Prometheus 表达式，按关键性等级设定 SLO 目标，并计算错误预算。
• 消耗速率告警 — 配置多窗口消耗速率规则，并通过严重级别路由、迟滞、抑制和分组，将告警噪声控制在 10% 以下。
• 仪表盘设计 — 制定符合「总览 > 服务 > 组件 > 实例」层级的 Grafana 规范，每个屏幕不超过 7 个面板，并提供基于角色的视图（SRE/开发/高管/运维）。
• 结构化日志与追踪 — 采用包含关联 ID 的 JSON 日志格式、遵循日志级别规范，并制定头部/尾部/自适应追踪采样策略。
• 运行手册与验证 — 为每个关键告警制定运行手册模板；验证每个 T1 服务是否都具备指标、日志、追踪和运行手册。
• 成本优化 — 制定指标/日志/追踪的保留期限等级并管理基数。

适用场景

• 为新的或现有的生产服务添加监控。
• 为某个服务等级定义 SLO 和错误预算。
• 调整告警规则，或减少告警疲劳/告警风暴。
• 设计 Grafana 仪表盘或基于角色的视图。
• 选择追踪采样策略或结构化日志架构。

首先确认

设计可观测性策略前，请确认以下信息。若有任何信息未知或不明确，请提问，不要自行假设：

• 服务类型与关键性等级 — api / pipeline / storage / ML，以及 T1–T3（决定 SLO 目标、错误预算计算方式和 slo_designer 标志）
• 面向用户还是内部服务 — 决定哪些黄金信号将成为 SLI，以及如何路由告警严重级别
• 主要问题：告警噪声还是覆盖缺口 — 决定是优化现有告警，还是设计新的消耗速率规则
• 仪表盘受众 — SRE / 开发 / 高管 / 运维，用于确定基于角色的面板布局和层级

停止规则：仅询问对输出影响最大的 2-3 项。如果用户表示“先直接起草”，则继续，并在文档开头列出假设。

工具

工具	用途	命令
slo_designer.py	根据服务定义生成 SLI/SLO 框架、错误预算和消耗速率告警	python scripts/slo_designer.py --service-type api --criticality high --user-facing true
alert_optimizer.py	分析告警配置中的噪声、覆盖缺口和重复项；生成优化报告	python scripts/alert_optimizer.py --input alerts.json --analyze-only
dashboard_generator.py	生成兼容 Grafana 的仪表盘 JSON，包含黄金信号和基于角色的视图	python scripts/dashboard_generator.py --service-type api --name "Payment Service"

参考资料

加载与任务相匹配的参考资料——保持此文件精简，按需查阅详细内容：

• references/slo-and-alerting.md — 8 步工作流、SLI/SLO 速查、错误预算计算、多窗口消耗率告警、告警分类、避免告警疲劳和黄金信号。设计 SLO 或告警时阅读。
• references/dashboards-logs-traces.md — 仪表板设计规则、结构化日志格式、跟踪采样策略、运行手册模板、完整的支付服务示例规范和成本优化。构建仪表板、日志、跟踪或运行手册时阅读。
• references/tools-integration-and-troubleshooting.md — 每个脚本的完整标志和输出参考、系统集成表（Prometheus/Grafana/Jaeger/PagerDuty）、故障排查表和成功标准目标。运行脚本或诊断故障时阅读。
• references/slo_cookbook.md — 定义和运行服务级目标的实用深入指南。需要超出速查内容的详细 SLO 方法时阅读。
• references/alert_design_patterns.md — 有效告警模式和反模式的深入指南。设计完整的告警策略时阅读。
• references/dashboard_best_practices.md — 全面的、以洞察为导向的仪表板设计最佳实践。从头构建仪表板系统时阅读。

范围与限制

涵盖：

• 面向请求驱动型、流水线型、存储型和 ML 服务的 SLI/SLO 框架设计。
• 多窗口消耗率告警生成和告警噪声优化。
• 兼容 Grafana 的仪表板规范，包含基于角色的布局（SRE、开发者、管理层、运维）。
• 结构化日志格式、跟踪采样策略选择和成本优化指南。

不涵盖：

• Prometheus、Grafana 或 Jaeger 的基础设施配置或 Terraform/Helm 配置——部署流水线请参阅 ci-cd-pipeline-builder。
• 事件响应工作流编排或事后复盘主持——运行手册编写请参阅 runbook-generator。
• 应用性能管理（APM）Agent 安装或特定供应商的 SDK 集成。
• 安全监控、SIEM 规则设计或合规审计日志——安全分析请参阅 skill-security-auditor。

集成点

技能	集成方式	数据流
runbook-generator	每个消耗率告警都会引用运行手册；运行手册生成器会使用告警定义来搭建调查步骤	Alert YAML --> runbook-generator --> 告警注释中链接的 Markdown 运行手册
ci-cd-pipeline-builder	部署事件会生成仪表板注释，并触发告警抑制窗口	流水线事件 --> Grafana 注释 + Alertmanager 静默规则
performance-profiler	延迟 SLI 违规会触发性能分析；分析结果可用于调整 SLO 目标	SLO 消耗率告警 --> 调用分析器 --> 优化后的延迟阈值
database-designer	数据库 SLI（查询延迟、连接成功率、复制延迟）与架构级健康检查保持一致	数据库架构元数据 --> 数据库类型服务的 SLI 指标表达式
tech-debt-tracker	错误预算耗尽信号会作为可靠性投入纳入技术债优先级排序	错误预算报告 --> 与 SLO 关联严重性的技术债待办事项
release-manager	发布就绪门禁会在批准部署前检查剩余错误预算	错误预算 API --> 发布门禁通过/失败决策