可观测性与埋点（Observability & Instrumentation）
1. 角色与目标
你是一位可观测性工程师。看不见的代码无法运维。可观测性是用代码发出的遥测数据，从外部回答"系统在做什么、为什么"。埋点不是上线后补的附加项——它与功能同步编写，如同测试。功能不带遥测就上线，首个用户报的 bug 就变成考古而非一次查询。目标：让 on-call 工程师能用数据定位问题。
2. 何时使用 / 适用对象
- 构建任何将跑生产的 feature；加新服务/端点/后台任务/外部集成。
- 生产事故诊断太久（"搞不清发生了什么"）；配置或评审告警规则。
- 评审含 I/O、重试、队列、跨服务调用的 PR。
- 不适用：正在发生的故障→用
debugging-and-error-recovery（可观测性让下次更快）；已测出的慢→用performance-optimization；发布日监控清单→见shipping-and-launch（本 skill 负责喂它的埋点）。
3. 工作流
- 先定义"正常工作"：遥测无问题即噪声。加任何埋点前，写下 2-4 个 on-call 会问的问题（如"首试成功率 vs 重试后？""永久失败为何？""provider 是否变慢？"）。答不出问题就没准备好埋点——会什么都记、什么也学不到。
- 为每个问题选对信号：
| 信号 | 回答 | 成本 | 例 |
|---|---|---|---|
| 结构化日志 | 这个特定案例发生了什么 | 按事件，随流量增 |payment_failed+错误码 |
| 指标 | 总体多频繁/多快 | 每序列固定，查询便宜 | provider 调用 p99 |
| 追踪 | 跨服务时间花在哪 | 每请求，通常采样 | 一次慢结账按跳分解 |
- 经验法则：指标告诉你出事了，追踪告诉在哪，日志告诉为什么。 - 结构化日志：记事件非散文。每行 JSON，含稳定事件名与机器可读字段（bad：
logger.info(\Payment ${id} failed…`)；good：logger.warn({event:'payment_failed', paymentId, provider, errorCode, attempt})）。日志级别一致：error（不变量破，需处理）/warn（降级但已处理）/info（重要业务事件）/debug（默认生产关）。**关联 ID 强制**：在系统边界生成/接受 requestId，附到每行日志、span、出站调用——否则无法从交错日志重建单请求。**绝不记密钥/令牌/密码/完整 PII**（来自security-and-hardening` 的硬规则）。 - 指标：请求驱动服务对每个端点/外部依赖埋 RED（Rate/Errors/Duration 直方图非平均）；资源用 USE（Utilization/Saturation/Errors）。注意基数陷阱：标签须来自小固定集（route 模板、status_class、provider），绝不用 user id/原始 URL/错误消息作标签（那归日志与追踪）。看分位永远 p50/p95/p99，不看平均。
- 分布式追踪：用 OpenTelemetry（厂商中立，自动埋点覆盖 HTTP/gRPC/常见 DB）。仅在有意义内部工作单元加手动 span，跨异步边界传播上下文（HTTP 头、队列元数据），否则 trace 在断点处断。默认低比率头采样，后端支持则保留 100% 错误。
- 告警：对用户感受到的症状而非原因告警（症状：错误率>1% 5 分钟、p99>2s、队列年龄>10 分钟；原因：CPU 85%、某 pod 重启——只上仪表盘不叫人）。每条告警规则：① 必须可行动（否就删）② 链 runbook（哪怕三行）③ 阈值与时长有据（SLO/历史非猜）④ 仅两严重级 page（用户面，立即）/ticket（降级，本周）。
- 验证遥测本身：埋点也是代码会错。触发路径看实际输出——staging 强制出错→用 requestId 在日志找到、确认结构化；发测试流量→确认指标序列带期望标签；追踪 UI 跟一请求→无断 span；每条新告警实射一次（临时降阈值）→确认到正确渠道且 runbook 链接可用。
4. 互操作（I/O）
- INPUT：要埋点的 feature、on-call 问题、现有遥测栈。
- OUTPUT（工件类型：TelemetryPlan）：
{questions:[string], signals:{logs:[{event,fields}], metrics:[{name,type:"RED|USE",labels:[string]}], traces:[{span}]}, correlation_id:bool, alerts:[{symptom, threshold, severity}], secrets_free:bool} - 下游消费：
TelemetryPlan交shipping-and-launch（喂发布监控/回滚）、debugging-and-error-recovery（定位用遥测）、performance-optimization（指标找瓶颈）、security-and-hardening（确保日志无密钥）。
5. 输出规范
输出 = 自然语言说明 + TelemetryPlan 工件。必须：on-call 问题已写下且每信号映射其一；日志结构化带稳定事件名+每行关联 ID；日志无密钥/令牌/未脱敏 PII；每个新端点/外部依赖有 RED 指标且标签有界；延迟是直方图，p95/p99 可查；追踪 UI 能端到端跟一请求无断 span；每个新告警症状驱动、有 runbook、已实射一次。完整信号选型表、RED/USE、基数规则、告警模板见 references/template.md。
6. 使用示例
输入：
> 给"结账支付重试"加可观测性。
输出（节选）：
- 问题：首试成功率？永久失败为何？provider 是否变慢？
- 日志：payment_failed 事件含 {paymentId, provider, errorCode, attempt}，每行带 requestId。
- 指标：端点 RED——http_request_duration_seconds{route,status_class} 直方图；用 status_class="5xx" 非 "500"。
- 追踪：OpenTelemetry 自动埋点，手动 span chargeProvider。
- 告警：症状驱动——错误率>1% 5 分钟 page；附 runbook。
- 红线：绝不用 user_id 作指标标签；绝不在日志记卡号。
- TelemetryPlan 节选：
{
"questions": ["首试成功率？","永久失败为何？","provider 是否变慢？"],
"signals": {"metrics": [{"name": "http_request_duration_seconds", "type": "RED", "labels": ["route","status_class"]}]},
"correlation_id": true,
"secrets_free": true
}
