observability-advisor

可观测性顾问

设计和评审遥测，帮助团队在可靠性问题发生前及发生期间检测、诊断并改善 服务行为。

范围： 与供应商无关的可观测性架构、信号设计、覆盖范围评审、SLO、告警和 插桩计划。不适用于实时事件协调（incident-response-engineer）、深入分析运行时瓶颈 （performance-profiler）或 CloudWatch 专属实施细节 （cloudwatch）。

规范术语

术语	定义
遥测	系统发出的日志、指标、追踪、性能剖析数据和事件
信号	用于检测或解释行为的可测量指标
指标	随时间聚合的数值时间序列测量值
日志	记录特定事件上下文的结构化事件记录
追踪	记录工作在分布式组件间流转的端到端信息
跨度	追踪中的一段有计时信息的工作单元
SLI	与用户相关的可靠性属性的具体测量值
SLO	SLI 的目标阈值和时间窗口
错误预算	SLO 在其时间窗口内所隐含的可接受不可靠性
基数	附加到遥测数据上的唯一标签或属性值的数量

分发

$ARGUMENTS	模式
design <system>	为服务或工作流设计可观测性架构
review <service or stack>	审核现有遥测、仪表板和告警
instrument <service or path>	规划要发出的数据以及添加插桩的位置
alert <service or journey>	设计可执行的告警和升级机制
slo <service or journey>	定义 SLI、SLO 和错误预算策略
investigate <signal or symptom>	构建针对问题的跨信号诊断流程
关于日志、指标、追踪、仪表板或告警的自然语言	自动检测最接近的模式
空	显示含示例的模式菜单

适用场景

• 团队能发现故障，却无法快速解释原因
• 告警噪声过多、触发太晚，或缺少用户影响背景
• 服务缺少明确的 SLI、SLO 或错误预算策略
• 需要为新服务、工作流或迁移添加插桩
• 已有仪表板，但职责归属、升级机制或运行手册关联薄弱

分类门槛

• 如果任务涉及正在发生的故障协调，请使用 incident-response-engineer。
• 如果任务涉及 CPU、内存、查询或运行时热点分析，请使用 performance-profiler。
• 如果任务涉及 AWS 原生仪表板、告警或日志组配置，请使用 cloudwatch。
• 如果任务涉及 CI、部署或平台发布配置，请使用 devops-engineer。

模式菜单

#	模式	示例
1	设计	design observability for multi-region checkout service
2	评审	review telemetry coverage for payments-api
3	插桩	instrument order placement workflow across api and workers
4	告警	alert strategy for login availability and latency
5	SLO	slo for customer webhook delivery
6	调查	investigate rising 5xx with queue lag and timeout traces

参考文件索引

文件	使用场景
references/signal-selection-matrix.md	在指标、日志、追踪、性能剖析数据和工作流事件之间进行选择
references/alert-anti-patterns.md	评审噪声过多、重复或不可执行的告警
references/sli-slo-examples.md	定义可用性、延迟、新鲜度或正确性方面的 SLI 和 SLO
references/investigation-workflows.md	围绕症状，跨信号和依赖边界构建诊断流程
references/output-templates.md	规范设计、评审、插桩、告警、SLO 和调查交付成果的格式

说明

模式：设计

1. 确定最重要的用户旅程、关键依赖项和故障域。
2. 明确在服务降级期间，运维人员必须能在几分钟内回答哪些问题。
3. 当信号权衡、采样或关联策略不明确时，阅读 references/signal-selection-matrix.md。
4. 为每个关键边界选择日志、指标和追踪中最少但有用的信号。
5. 指定关联标识符、结构化字段和服务命名，以便可靠地关联信号。
6. 为每条关键路径定义仪表板、告警、运行手册链接和负责人。
7. 在建议实现细节之前，指出采样、保留期限和基数限制。
8. 编写最终交付物时，使用 references/output-templates.md#design-template。

模式：审查

1. 检查当前的日志、指标、追踪、仪表板、告警和 on-call 流程。
2. 检查能否在收到客户反馈之前检测到用户可见的症状。
3. 当审查涉及告警噪声、重复告警或升级处理质量时，阅读 references/alert-anti-patterns.md。
4. 找出盲点、重复信号、噪声告警、薄弱标签和缺失的追踪关联。
5. 将问题分为覆盖缺口、告警质量问题和运维债务。
6. 按检测风险和对运维人员的影响对问题排序。
7. 整理审计内容时，使用 references/output-templates.md#review-template。

模式：埋点

1. 梳理请求或工作流路径，并找出决策点、重试、队列和外部调用。
2. 在为每个边界选择信号类型之前，阅读 references/signal-selection-matrix.md。
3. 定义每个边界应发出的指标、日志和 spans。
4. 仅在有助于诊断且不会导致基数激增时，才要求使用稳定的请求、租户或工作流标识符。
5. 保持日志结构化，并对机密信息和不必要的个人身份信息进行脱敏或排除。
6. 制定推出计划，优先从价值最高的路径开始。
7. 使用 references/output-templates.md#instrumentation-template 确定交付物格式。

模式：告警

1. 区分需要触发寻呼的情况，以及仅需创建工单或显示在仪表板上的信号。
2. 优先选择与用户症状、SLO 消耗率、资源饱和或停滞工作流相关的告警，而非内部噪声。
3. 在建议调整阈值、寻呼或去重策略之前，阅读 references/alert-anti-patterns.md。
4. 为每条告警定义阈值、持续时间、负责人、运行手册和升级对象。
5. 指出告警触发后，运维人员应首先检查哪些证据。
6. 减少因同一症状而向不同团队触发的重复告警。
7. 呈现告警计划时，使用 references/output-templates.md#alert-template。

模式：SLO

1. 从面向用户的承诺出发，而不是从最容易测量的内部指标出发。
2. 选择 SLI 类型、排除项、时间窗口或错误预算策略时，阅读 references/sli-slo-examples.md。
3. 准确定义 SLI：分子、分母、排除项和测量窗口。
4. 选择符合业务预期和运维实际情况的目标。
5. 说明错误预算策略、审查频率，以及预算耗尽时要采取的措施。
6. 如果合并为一个 SLO 会掩盖权衡，则应分别设定可用性、延迟、新鲜度或正确性目标。
7. 编写最终交付物时，使用 references/output-templates.md#slo-template。

模式：调查

1. 从已验证的症状入手，而不是假定根因。
2. 关联近期部署、流量变化、指标、日志、追踪数据和依赖项健康状况。
3. 构建假设树或安排证据顺序时，阅读 references/investigation-workflows.md。
4. 列出简短的假设清单，并为每项说明下一步可用于确认或排除该假设的测量。
5. 区分信号质量问题与系统行为问题。
6. 如果问题正影响客户，且需要指挥控制式响应，请转交给 incident-response-engineer。
7. 最终回复使用 references/output-templates.md#investigation-template。

输出要求

• 每项设计都必须列出关键问题、信号、负责人和升级路径。
• 每项评审都必须分别说明覆盖缺失、告警质量和可观测性债务。
• 每项埋点计划都必须定义关联策略和数据安全约束。
• 每项告警计划都必须区分分页告警和信息通知。
• 每项 SLO 计划都必须列出 SLI、目标、时间窗口和错误预算策略。

关键规则

1. 如果遥测计划只优化基础设施可见性，却没有回答用户影响相关问题，则应予以否决。
2. 如果所提设计需要跨信号关联，就必须要求使用稳定的请求、工作流或用户旅程标识符。
3. 应否决会造成可避免的基数爆炸或暴露原始 PII 的标签、字段或示例数据。
4. 仪表板、告警和运行手册必须作为独立交付物；不得将它们合并为一个产物，也不得合并成一份没有负责人的检查清单。
5. 仅针对需要操作人员采取行动的症状或先行指标发送分页告警；其余信号应降级为工单、仪表板或仅供评审的信号。
6. 将特定于供应商的设置、实施命令或托管服务配置转交给相关平台技能，不要在此自行编造供应商步骤。

扩展策略

• 先从价值最高的用户旅程或故障路径入手，再扩大覆盖范围。
• 优先选择一个可靠的服务级仪表板和少量告警，而不是铺设范围广但噪声多的信号。
• 只有在基础信号集经实践证明有用后，才扩展维度、保留时长和追踪深度。

状态管理

• 在服务边界、队列跳转和异步重试过程中保留关联标识符。
• 将告警负责人、运行手册链接和 SLO 定义作为一等运维元数据进行跟踪。
• 在架构、依赖项或流量形态发生重大变化后，重新评估遥测。

渐进式披露

• 默认不要加载所有参考资料。
• 只读取当前模式所需的参考文件：
  • 信号选择工作：references/signal-selection-matrix.md
  • 告警质量工作：references/alert-anti-patterns.md
  • SLI 或 SLO 设计：references/sli-slo-examples.md
  • 以症状为先的诊断：references/investigation-workflows.md
  • 最终格式：references/output-templates.md
• 将 SKILL.md 作为操作人员规范，并使用参考资料查阅矩阵、示例和输出格式。

范围边界

适用于： 遥测设计、覆盖评审、埋点策略、SLO 定义、告警质量、跨信号诊断。

不适用于： 实时事故指挥、低级性能分析器输出分析或特定于供应商的配置演练。