可观测性与埋点

要解决的问题

功能不带遥测就上线，首个用户报的 bug 就变成考古——团队只能翻交错日志、猜复现路径、靠记忆还原现场。可观测性不是上线后补的附加项，它与功能同步编写，如同测试。本技能面向 on-call 工程师：让问题定位从「猜」变成「查」。

技能如何工作

1. 先定义「正常工作」：加任何埋点前，写下 2-4 个 on-call 会问的问题，例如首试成功率、永久失败原因、provider 是否变慢。答不出问题就没准备好埋点，否则会什么都记、什么也学不到。

2. 按问题选信号：

• 结构化日志：回答「这个特定案例发生了什么」，记事件而非散文，每行 JSON 含稳定事件名与机器可读字段
• 指标：回答「多频繁、多快」，固定成本、查询便宜，如 provider 调用 p99
• 追踪：回答「跨服务时间花在哪」，按请求记录、通常采样，OpenTelemetry 自动埋点 HTTP/gRPC/常见 DB

经验法则：指标告诉你出事了，追踪告诉你在哪，日志告诉你为什么。

3. 三条硬规则贯穿所有信号：

• 日志级别语义一致（error/warn/info/debug），关联 ID 在系统边界生成并附到每行日志、span、出站调用
• 指标标签来自小固定集（route 模板、status_class、provider），绝不用 user id 或原始 URL 作标签；延迟是直方图，只看 p50/p95/p99
• 日志绝不记密钥、令牌、密码或完整 PII

4. 告警面向症状，不面向原因：对用户感受到的（错误率、p99 延迟、队列年龄）告警；CPU、pod 重启这类原因只上仪表盘。每条规则必须可行动、链 runbook、阈值有 SLO 依据，且仅保留 page/ticket 两级。

5. 验证遥测本身：埋点也是代码会错。在 staging 强制出错验证日志可检索，发测试流量确认指标标签，跟一请求确认追踪无断点，每条新告警实射一次。

适用边界

• 适用：构建将跑生产的 feature；新增服务、端点、后台任务、外部集成；配置或评审告警；评审含 I/O、重试、队列、跨服务调用的 PR
• 不适用：正在发生的故障（用 debugging-and-error-recovery，本技能让下次更快）；已定位的慢（用 performance-optimization）；发布日监控清单（见 shipping-and-launch，本技能负责喂它的埋点）