observability-and-instrumentation

可观测性与埋点

概览

无法观测的代码，就无法运维。可观测性是指：借助代码发出的 telemetry，从外部回答“系统正在做什么、为什么”。埋点不是上线后的附加项——它和功能代码一起写，就像测试一样。如果一个功能在没有 telemetry 的情况下发布，第一个用户上报的 bug 就变成了考古，而不是查询。

何时使用

• 构建任何会跑在生产环境的功能
• 添加新的服务、endpoint、后台 job 或外部集成
• 一次生产事故的诊断花了太久（"we couldn't tell what happened"）
• 建立或评审告警规则
• 评审一个新增 I/O、重试、队列或跨服务调用的 PR

不适用于：

• 诊断正在发生的故障——用 debugging-and-error-recovery skill（可观测性正是让这个 skill 下次跑得快的东西）
• 对已测量出的慢做 profiling 和优化——用 performance-optimization skill
• 发布日的监控 checklist 和回滚触发器——见 shipping-and-launch skill；本 skill 覆盖的是喂养它们的那层埋点

流程

1. 先定义“能工作”，再埋点

没有问题支撑的 telemetry 就是噪音。在添加任何埋点之前，写下 on-call 工程师针对这个功能会问的 2–4 个问题：

FEATURE: checkout payment retry
QUESTIONS ON-CALL WILL ASK:
1. What fraction of payments succeed on first attempt vs after retry?
2. When a payment fails permanently, why? (provider error? timeout? validation?)
3. Is the payment provider slower than usual?
→ Every signal below must help answer one of these.

如果你说不出这些问题，你就还没准备好埋点——你会把一切写进日志，然后什么也学不到。

2. 为每个问题选对信号

信号	回答什么	成本特征	例子
结构化日志	“这个具体案例里发生了什么？”	按事件计；随流量增长	带 provider 错误码的 payment_failed
指标	“聚合来看，多频繁 / 多快？”	每个 series 固定；查询便宜	provider 调用的 p99 延迟
Trace	“时间花在了跨服务的哪一段？”	按请求计；通常采样	一次慢 checkout，按 hop 拆开看

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

3. 结构化日志

记录事件，不是散文。每一行日志都是一个 JSON object，带有稳定的事件名和机器可读的字段：

// BAD: string interpolation — unqueryable, inconsistent
logger.info(`Payment ${id} failed for user ${userId} after ${n} retries`);

// GOOD: stable event name + structured fields
logger.warn({
  event: 'payment_failed',
  paymentId: id,
  provider: 'stripe',
  errorCode: err.code,
  attempt: n,
}, 'payment failed');

日志级别——用得体一致：

级别	含义	On-call 的动作
error	不变量被打破；可能有人需要采取行动	调查
warn	降级但已处理（重试成功、用了 fallback）	留意趋势
info	重要的业务事件（下单完成、job 结束）	无
debug	诊断细节	生产环境默认关闭

Correlation ID 是强制的。 在系统边界生成（或接受）一个 request ID，并把它附加到每一行日志、每个 span 和每次对外调用上。没有它，你无法从交错的日志里重建出单个请求：