specsfy-specialist-observability

可观测性

适用场景

• 当请求涉及埋点（日志、指标、追踪）、事故调查、SLI/SLO 定义或构建仪表板/告警时使用。
• 当需要定义授权继续、暂停或回滚发布的客观信号时也使用。
• 不要用于诊断已发现的特定延迟问题的根本原因——使用 $specsfy-specialist-performance-engineering 进行性能分析和优化；这里的可观测性关注的是信号系统的设计，而不是调查已完成埋点的单个问题。
• 当此处定义的信号将决定发布的 failure_action 时，与 $specsfy-specialist-delivery-engineering 配合使用。

流程

1. 在选择任何工具之前，先明确实际的运维问题（“结账功能对用户来说正常吗？”）和关键用户旅程。
2. 定义 SLI（可测量的指标）和 SLO（可接受的目标）；对于重要性足以构成理由的服务，明确错误预算。
3. 梳理信任边界/系统边界（HTTP、队列、作业、数据库）以及需要跨越这些边界的关联上下文（trace id、request id）。
4. 从设计阶段开始，就以受控的基数埋点记录事件、指标和 span，而不是事后补救。
5. 保护 telemetry 中的敏感数据（redaction、遮蔽），并按信号类型定义保留策略。
6. 按决策组织仪表板（这个页面能帮助我做出什么决策？），按行动组织告警（告警触发时我该怎么做？）。
7. 在信任 telemetry 并于真实事故中使用之前，先验证它在成功、失败和部分降级这三种状态下的表现。

模式

• 使用结构化日志（键值对或 JSON），包含命名事件、严重性、关联标识符和最低限度的必要上下文——绝不使用需要通过 regex 提取数据的自由拼接字符串。
• 指标只使用基数有限且已知的标签（规范化的 endpoint、状态码、tenant（如果 tenant 数量较少））；绝不使用 user id、带原始 query string 的 URL 或原始错误消息作为标签——每个唯一标签值都会使存储的序列数量成倍增加。
• 追踪在 HTTP、队列和异步作业之间传递时保留相同的关联上下文——如果 trace 在队列边界处“中断”，就无法排查最常见的问题（服务间的分布式延迟）。
• 告警应反映对用户的实际影响或违反 SLO 的迫近风险，并且每条告警都要有负责人和可访问的 runbook——没有关联行动的告警只是噪声，会让团队习惯忽略告警。
• 仪表板从总体健康视图（RED/USE）开始，并支持逐层深入查看细粒度信号，而不是反过来。
• 即使降低高流量正常路径的采样率，trace 采样仍应保留 100% 的错误和关键业务事务。
• telemetry 本身应安全地失效（性能降级，但不致使产品宕机）——指标导出器离线绝不能导致被埋点的应用宕机。

反模式

• 不加结构、也不统一严重性级别地“记录所有内容”：这会增加存储成本，并降低事故期间找到相关事件的实际能力——日志量不等于可观测性。
• 使用高基数标签的指标（例如，将 user_id 或 order_id 用作标签）：这会使存储的时间序列数量激增，可能导致指标后端宕机或成本大幅增加。
• 根据原因指标而不是症状指标配置告警（例如，对“CPU 使用率过高”告警，而不是对“错误率/延迟超过 SLO”告警）：这会在无害的峰值期间产生噪声，也不一定能检测到对用户的实际影响。
• 仪表板只是因为“当时看起来有用”而存在，却没有定期审核：这会积累过时的面板，使其在事故期间与真正重要的面板争夺注意力。

验证

• 在受控场景中端到端生成遥测数据，并确认关联关系（trace id）贯穿所有已映射的边界。
• 检查预计基数、预估成本、配置的保留期限，并确认敏感字段在离开服务前经过脱敏处理。
• 确认配置的告警确实会在预期场景中触发（测试或模拟），且关联的运行手册可由未编写代码的人执行。
• 针对已知故障场景运行团队在真实事件期间会使用的查询，确认它们能在有效时间内返回预期信号。
• 不要仅因存在仪表板就宣称系统“可观测”；真正的证明是团队无需访问代码或数据库，仅凭遥测数据就能回答最初的运维问题。

相关技能

• $specsfy-specialist-server-report 汇总日志、服务和磁盘使用情况， 生成按主机分类的报告，并通过 Ansible 以只读方式采集数据。

• $specsfy-specialist-debugging 利用这些信号隔离根因，并在证据不足时要求 增加检测。

• $specsfy-specialist-docker 和 $specsfy-specialist-docker-swarm 暴露 运行时、服务和节点信号；此技能负责定义关联关系和决策。

• $specsfy-specialist-postgres 和 $specsfy-specialist-redis 生成数据／缓存信号， 其基数和保留期限由此处控制。

• $specsfy-specialist-web-api-design 定义契约中的关联关系和错误； 此技能衡量端点在运行中的行为。

• $specsfy-specialist-performance-engineering 用于诊断此处定义的信号 已检测到的延迟或瓶颈的根因。

• 当此处定义的健康信号会影响继续或回滚发布的决策时，使用 $specsfy-specialist-delivery-engineering。

• 当遥测需要记录（或有意不记录）安全事件时，使用 $specsfy-specialist-application-security。

请阅读 references/standards.md，了解可观测性的支柱、 仪表板框架（RED/USE）、SLI/SLO 和 OpenTelemetry 官方来源。