可观测性设计要回答一个故障中的实际问题:哪个用户流程受影响、故障发生在哪一段、哪些证据能缩小排查范围?这个 Skill 在实现前检查遥测设计是否具备这些能力。

什么时候使用

当团队需要评审日志、指标、追踪、上下文传递、SLO 与 SLI、告警、采样、保留策略、隐私或成本设计时,可以使用可观测性设计复核。它检查提供的设计材料并产出 OBS-## 发现;不会查询生产信号、执行探测、分析真实事故或判断系统健康。

复核流程

先记录服务边界、业务流程、环境、版本和时间范围,再把材料分类为 known、missing、conflicting、stale、out_of_scope 或 assumptions。随后沿着一个故障路径,检查各类信号能否共同说明发生了什么。

信号范围需要回答的问题
日志哪个事件和字段能标识对象与结果?敏感值是否经过遮蔽?
指标单位、维度、基数和聚合语义是否明确?
追踪跨服务和异步边界时,上下文能否继续传递?
SLO 与 SLI服务目标、指标、统计窗口和测量规则是否有明确来源?
仪表盘每个面板是否对应具体的运维或产品决策,单位和上下文是否清楚?
告警什么条件会触发告警、谁负责响应、之后要采取什么动作?
运维约束采样、保留、访问权限和成本是否已说明?

不要根据平台默认值补写缺失的 SLO、阈值、保留期限或采样率。每项判断都要保留来源和证据状态。

示例:结算流程的关联链路

以下是说明性设计复核示例,不代表真实服务已经过检查:

提供的材料复核可以得出的判断仍未证明的事项
结算设计列出网关请求 ID、支付请求 ID 和订单事件 ID,但没有关联规则设计材料缺少跨步骤的关联约定,应标为待补证不能据此断定运行中的追踪一定断链
告警规则写了触发条件,却没有响应负责人或运行手册动作响应交接信息不完整,需补充负责角色和首个排查动作不能证明告警已经触发,或值班流程能完成响应

补证时,可以用脱敏合成请求检查计划中的追踪片段,并保留请求身份、环境、时间范围和原始信号。只有设计文档时,结论仍限于设计复核。

交付哪些内容

每条 OBS-## 都应列出信号和对象、来源与证据状态、预期字段或语义、缺口与影响、检测动作、负责人角色、关闭条件和验证方法。事实、基于证据的推断、建议和人工决策要分开写。如果缺少运行身份、时间、环境或原始信号,运行结论应标记为未验证或未评估。

实践建议

  • 先处理影响大的缺口,并请求足以解决问题的最小证据或安全检查。
  • 分开记录事实、证据支持的推断、建议和人工决策;不要把假设写成结论。

结论边界

仪表盘只能证明设计中包含一个视图,不能证明告警真的触发,也不能证明服务健康。不要代替负责人选择 SLO、事故等级、采样率、保留期限或成本预算。纯设计复核也不应接触生产数据。

相关 Skill

安装与调用

从 Awesome QA Skills 仓库安装这个独立 Skill:

npx skills add https://github.com/naodeng/awesome-qa-skills/tree/main/skills/zh --skill observability-design-review

调用 observability-design-review 时,提供遥测设计、范围、环境、现有证据,以及本次复核要支持的决策。

可以直接使用下面的请求模板:

请使用 observability-design-review Skill。
服务和流程:[边界、版本和环境]。
复核材料:[日志、指标、Trace、告警及 SLI/SLO 设计]。
需要支持的决策:[运维或产品要回答的问题]。
约束:[隐私、保留、采样和成本规则]。
找出缺失或冲突的证据,并提出最小安全验证。不要查询生产系统,也不要根据设计文档推断系统健康。

常见问题

有仪表盘设计就能证明系统可观测吗?

不能。设计只能说明计划了一个视图。要判断实际运行时是否可观测,需要真实信号带有身份、时间、环境等信息,并且能关联到足以回答排查问题的证据。

SLI 或告警阈值没有定义怎么办?

标记为缺失,并指出需要由谁定义。不要套用平台默认值,也不要自行设目标。

源文件

使用前请阅读可观测性设计复核提示词: https://github.com/naodeng/awesome-qa-skills/tree/main/skills/zh/testing-types/observability-design-review/prompts/observability-design-review.md。源目录: https://github.com/naodeng/awesome-qa-skills/tree/main/skills/zh/testing-types/observability-design-review;包含入口文件和配套评估材料。

更多参考

分享