用途
该技能适用于设计或评审 Web 应用、API、SaaS 平台、移动后端和 AI 系统的可观测性方案，涵盖日志、指标、追踪、告警、SLO、仪表盘、审计事件以及生产遥测。其目标是让生产环境中的故障可被理解、可被行动、可被界定范围，而不仅仅是做数据分析。
当任务需要可复用的判断、领域约束或经过验证的工作流，而非临时建议时，适合使用本技能。
不适用场景
- 任务与可观测性监控无关，或更适合由更具体的配套技能处理。
- 请求只需要一个简单答案，本技能的约束或参考材料没有实质帮助。
所需输入
- 收集相关项目背景、约束条件和要解决的具体问题；仅在需要时加载参考文件。
- 确认期望的交付物：设计、代码、评审、迁移计划、审计或文档。
工作流
- 先阅读 SKILL.md，然后只加载任务所需的深层参考文件。
- 应用本技能中有序的指导、检查清单和决策规则，而不是挑选孤立的片段。
- 产出交付物时，在重要处明确假设、风险和后续工作。
可观测性工作流
1. 识别关键流程
对每个关键流程定义：
- 触发条件
- 预期成功结果
- 已知失败模式
- 降级时的业务影响
- 失败时操作员的行动
优先对影响最大的流程进行埋点。
2. 按问题定义遥测
对每个重要信号，询问：
- 这个信号将回答什么问题？
- 谁需要这个答案？
- 他们需要多快看到？
使用以下映射：
- 日志用于详细的取证上下文
- 指标用于趋势、速率、饱和度和告警
- 追踪用于多跳延迟和依赖诊断
- 审计事件用于重要业务或安全操作
- 性能剖析用于 CPU、内存、锁或成本行为重要时
3. 设计关联
每个请求、任务和工作流都应具备：
- 请求或追踪 ID
- 操作者或服务身份
- 适用时的租户或归属上下文
- 环境和版本元数据
- 发布标记或部署版本
- 重要下游调用的依赖标识
没有关联，遥测就会变成噪音。
4. 设计高上下文事件
- 优先使用带有有用维度的结构化事件，而非稀疏文本字符串。
- 排除个人敏感或机密字段，但不要剥离调试所需的上下文。
- 谨慎处理基数。高基数维度在能回答真实调试问题时可能很有价值。
- 为长时间运行的任务和工作流发出状态转换，以便操作员重建部分失败。
5. 定义 SLO 和告警
- 将 SLO 用于面向用户的可靠性，而不是每个内部指标。
- 定义：成功指标、时间窗口、目标阈值、错误预算影响。
- 告警应仅在需要立即行动时触发。
6. 构建用于诊断的仪表盘
仪表盘应回答：
- 什么坏了？
- 谁受影响？
- 瓶颈在哪里？
- 最近有什么变化？
- 操作员下一步应该做什么？
不要创建无法指导行动的虚荣仪表盘。
遥测标准
日志
- 使用结构化日志。
- 包含 ID、操作者上下文、租户上下文、路由或任务名称以及结果。
- 记录失败时提供足够上下文以便调试，但绝不泄露机密或敏感载荷。
- 将业务审计日志与应用诊断日志分开。
指标
跟踪：
- 请求速率
- 错误率
- 延迟百分位数
- 资源饱和度
- 队列深度和滞后
- 重试和回退计数
- 相关时的缓存命中率
- 相关时的成本或 token 使用量
- 池、工作线程、速率限制或线程使用的饱和度信号
优先使用百分位数和速率，而非平均值。
追踪
追踪：
- 跨服务或进程边界的请求
- 昂贵的后台工作流
- 外部依赖
- 具有多个阶段的 AI 或检索管道
- 平台支持时的部署标记和重要异步转换
审计事件
以下情况需要审计事件：
- 认证和角色变更
- 影响财务或账本的操作
- 权益变更
- 导出、删除和审批
- 具有外部或特权副作用的 AI 操作
AI 与成本感知遥测
对于 AI 系统，捕获：
- 模型、提示版本和工具路径
- 检索阶段和来源数量
- token、延迟和成本预算
- 可用时的评估结果或质量检查
- 回退、拒绝和验证失败
告警设计规则
- 对需要立即人工行动的症状进行寻呼。
- 对可以等待的趋势或退化创建工单。
- 其他所有内容放入仪表盘。
- 避免没有运行手册路径的告警。
- 包含环境、服务、版本、影响和可能的初步检查。
参见 references/alert-design.md。
交付物
对于重要系统，产出：
- 关键流程的遥测映射
- SLO 定义
- 带严重性和负责人的告警列表
- 仪表盘大纲
- 审计事件列表
- 追踪和关联 ID 策略
- 基数和敏感数据防护栏
评审检查清单
- 关键流程有明确的遥测。
- ID 和租户上下文在日志、指标和追踪之间关联。
- 事件包含足够上下文以便调试，且不泄露不安全数据。
- 告警映射到操作员行动，而不仅仅是好奇心。
- SLO 反映用户影响，而非内部实现琐事。
- 为重要操作定义了审计事件。
- 敏感数据从遥测中排除或脱敏。
证据产出
| 类别 | 产物 | 格式 | 示例 |
|---|---|---|---|
| 可运维性 | SLO 记录 | 按 skill-composition-standards/references/slo-template.md 的 Markdown 文档 | docs/slo/checkout-service.md |
| 可运维性 | 可观测性接线说明 | 列出已接线的日志、指标、追踪和仪表盘的 Markdown 文档 | docs/observability/checkout-wiring.md |
| 可运维性 | 告警目录 | 列出告警名称、阈值和运行手册链接的 Markdown 文档 | docs/observability/checkout-alerts.md |
参考文件
阅读核心工作流后，使用 references/ 目录获取深层细节。
- 当任务是平台建设、SigNoz/OpenTelemetry 栈设计、收集器拓扑、存储、保留或仪表盘基础设施时，加载 references/observability-platform.md。
- references/alert-design.md：告警严重性和路由规则。
- references/diagnosis-first-observability.md：事件设计、基数、发布标记和 AI 遥测。
- references/slo-template.md：SLO 模板和服务问题。
加载顺序
- 加载 world-class-engineering。
- 在最终确定架构、API、任务或发布设计之前加载本技能。
- 与 deployment-release-engineering 配合使用，以实现发布和事件可见性。
质量标准和反模式
质量标准：
- 保持输出面向执行、简洁，并与仓库的基线工程标准一致。
- 除非技能明确要求更强的标准，否则保持与现有项目约定兼容。
- 优先使用确定性、可评审的步骤，而非模糊建议或特定工具的魔法。
反模式：
- 将示例视为复制粘贴的真理，而不检查适用性、约束或失败模式。
- 默认加载每个参考文件，而不是使用渐进式披露。
输出
- 适合任务的具体结果：实施指导、评审发现、架构决策、模板或生成的产物。
- 当任务无法仅从可用上下文完成时，明确假设、权衡或未解决的差距。
- 在能实质改善执行时，提供使用的参考、配套技能或后续行动。