可观测性与埋点

你要解决什么问题

一个功能上线了，某天用户反馈「支付偶尔失败」。你打开日志，发现只有零散的字符串拼接输出，没有请求 ID，无法把一次失败的完整链路串起来。你不清楚是哪个依赖变慢、哪次重试耗尽了配额，只能猜。

这就是埋点缺失的代价：没有遥测的功能，出问题时不是查询，而是考古。可观测性不是为了好看板，而是为了让值班工程师能回答「系统在做什么、为什么这样做」。Instrumentation 也不是上线前的补丁，它应该和功能代码一起写，就像测试一样。

这个技能怎么工作

技能的核心流程是：先定义问题，再选信号，最后验证。

第一步：先写下要回答的问题

在写任何埋点之前，先列出值班工程师会问的 2–4 个问题。答不出这些问题就动手，结果就是记录一切、学到 nothing。

第二步：为每个问题选对信号

| 信号 | 回答什么 | 成本 |
|---|---|---|
| 结构化日志 | 这个具体案例发生了什么？为什么？ |
| 指标 Metric | 聚合上看多频繁、多快？ |
| 分布式追踪 Trace | 时间花在跨服务的哪一段？ |

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

第三步：日志要结构化，ID 要贯穿

每行日志是一个 JSON 对象，带稳定的事件名（如 payment_failed）和可机读字段，而不是散文。等级（error/warn/info/debug）要一致使用。关联 ID 是强制的：在系统边界生成或接收 request ID，附到每一行日志、每个 span、每个外呼上，否则无法从交错日志中还原一次请求。

硬规则：绝不记录 secret、token、密码或完整 PII。遥测管道是经典的数据泄漏路径。

第四步：指标用 RED/USE，基数是最大陷阱

请求驱动的服务给每个 endpoint 和外部依赖埋 RED（Rate、Errors、Duration）；资源型用 USE（Utilization、Saturation、Errors）。时延一律用直方图，绝不用平均值——平均值会掩盖那 1% 体验糟糕的用户，要看 p50/p95/p99。

标签必须来自小的固定集合（路由模板、状态码类别、provider 名）。基数是常见故障模式：不要用 user ID、原始 URL、错误消息文本做标签，那属于日志和追踪。

第五步：追踪用 OpenTelemetry

它是厂商中立标准，自动埋点覆盖 HTTP、gRPC、常见数据库客户端，几乎零代码。只在有意义的内部工作单元（如 applyDiscounts、chargeProvider）手动加 span，并把上下文跨过每个异步边界传播，否则链路在断点处就断了。

第六步：告警要盯症状，不盯原因

基于原因的告警（CPU、内存）会在没事时狂响、在没预料到的故障上沉默。应该对用户感受到的症状告警：面向用户的错误率、用户侧时延。每条告警必须可执行、挂 runbook 链接、有经过 SLO 或历史数据支撑的阈值和持续时间，且只用 page 和 ticket 两级。

第七步：验证遥测本身

埋点也是代码，会写错。在 staging 强制触发错误，用 requestId 找到它；发测试流量确认指标序列和标签正确；在 tracing UI 里跟一次请求，确认没有断 span；临时调低阈值，把每条新告警试触发一次。

适用边界

适合：生产功能开发、新服务/endpoint/后台任务/外部集成接入、事故诊断太慢时、告警规则评审、审查含 I/O、重试、队列、跨服务调用的 PR。

不适合：排查正在发生的故障（用 debugging 技能，本技能让它下次更快）、性能剖析（用 performance-optimization）、发布日监控清单（用 shipping-and-launch）。

红旗信号：带重试和队列却零遥测的 PR、字符串拼接日志、无 request ID、用 user ID 做标签、只记平均时延、每天响却没人管的告警、日志里出现 secret。