observability-and-instrumentation
给代码埋点,让生产行为可见、可诊断。在添加日志、指标、tracing 或告警时使用。在构建任何会跑在生产环境的功能、而你需要证据证明它能工作时使用。在生产问题被上报、但仅凭现有数据说不清发生了什么时使用。
vinvcn · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add vinvcn/addyosmani-agent-skills-zh --skill observability-and-instrumentationAbout this skill
name: observability-and-instrumentation description: 给代码埋点,让生产行为可见、可诊断。在添加日志、指标、tracing 或告警时使用。在构建任何会跑在生产环境的功能、而你需要证据证明它能工作时使用。在生产问题被上报、但仅凭现有数据说不清发生了什么时使用。
可观测性与埋点
概览
无法观测的代码,就无法运维。可观测性是指:借助代码发出的 telemetry,从外部回答“系统正在做什么、为什么”。埋点不是上线后的附加项——它和功能代码一起写,就像测试一样。如果一个功能在没有 telemetry 的情况下发布,第一个用户上报的 bug 就变成了考古,而不是查询。
何时使用
- 构建任何会跑在生产环境的功能
- 添加新的服务、endpoint、后台 job 或外部集成
- 一次生产事故的诊断花了太久("we couldn't tell what happened")
- 建立或评审告警规则
- 评审一个新增 I/O、重试、队列或跨服务调用的 PR
不适用于:
- 诊断正在发生的故障——用
debugging-and-error-recoveryskill(可观测性正是让这个 skill 下次跑得快的东西) - 对已测量出的慢做 profiling 和优化——用
performance-optimizationskill - 发布日的监控 checklist 和回滚触发器——见
shipping-and-launchskill;本 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 和每次对外调用上。没有它,你无法从交错的日志里重建出单个请求:
// Express: child logger per request, ID propagated downstream
app.use((req, res, next) => {
req.id = req.headers['x-request-id'] ?? crypto.randomUUID();
req.log = logger.child({ requestId: req.id });
res.setHeader('x-request-id', req.id);
next();
});
当多个入口点写同一份日志时,给日志标出入口点。 Correlation ID 标识一次运行,但说不出是哪条代码路径发起了它。同一个 job 被 scheduler、replay endpoint 和手动 CLI 运行各触发一次,会在同一个 sink 里产出可以互相顶替的行,于是行的归属只能靠排除法——交叉阅读 scheduler 的历史、进程表、部署日志——而这套论证只在外层那些记录恰好还存在时才成立。在运行启动的地方、紧挨着 correlation ID 给入口点打标记,并让两个字段以同样的方式传播:
// One helper for every entry point: the run's own logger carries both fields.
// `entryPoint`, not `source` — ECS reserves `source.*` for network fields.
export const runLog = (entryPoint: 'scheduler' | 'replay_endpoint' | 'cli', runId: string) =>
logger.child({ entryPoint, requestId: runId });
// scheduler tick -> runLog('scheduler', crypto.randomUUID())
// POST /jobs/:id/replay -> runLog('replay_endpoint', req.id)
// CLI invocation -> runLog('cli', process.env.RUN_ID ?? crypto.randomUUID())
这两个字段必须和 correlation ID 跨越同样的边界——队列 metadata、HTTP header——否则 worker 只能重新推断入口点、靠猜。一个仅仅与某个入口点存在相关性的字段只是一个线索,不是归因:任何能触发这个 job 的东西都能复现它。
绝不记录 secret、token、密码或完整 PII。 这是来自 security-and-hardening skill 的一条硬性规则——telemetry pipeline 是一条经典的数据泄露路径。按 allowlist 记录字段;不要整包记录 request body。
4. 指标
对 request-driven 的服务,在每个 endpoint 和每个外部依赖上埋 RED:Rate(请求/秒)、Errors(失败率)、Duration(延迟 histogram,不是平均值)。对资源(队列、连接池、主机),用 USE:Utilization、Saturation、Errors。
和 tracing 一样,厂商中立的路径是 OpenTelemetry metrics API(与第 5 步相同的 SDK 和 context)。下面的例子用的是 Prometheus 的 prom-client——一个常见的后端选择,不是唯一的选择;RED/USE 和 cardinality 规则两种路径下完全相同。
import { Histogram } from 'prom-client';
const httpDuration = new Histogram({
name: 'http_request_duration_seconds',
help: 'HTTP request duration',
labelNames: ['method', 'route', 'status_class'], // '2xx', not '200'
buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
});
Cardinality 就是那个故障模式。 每一个唯一的 label 组合都是一条独立的 time series。Label 必须来自小而固定的集合(route template、status class、provider 名)。绝不要用 user ID、原始 URL、错误消息或其他无界值做 label——那些属于日志和 trace。
OK as label: route="/api/tasks/:id" status_class="5xx" provider="stripe"
NEVER a label: user_id, email, request_id, full URL, error message text
永不追踪平均值,永远追踪百分位:平均值会藏起那 1% 体验极差的用户。用 histogram,读 p50/p95/p99。
5. 分布式 tracing
用 OpenTelemetry——它是厂商中立的标准,而 auto-instrumentation 以近乎零代码覆盖 HTTP、gRPC 和常见 DB client:
// tracing.ts — must be imported before anything else
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
const sdk = new NodeSDK({
serviceName: 'checkout-service',
instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();
只在有意义的内部工作单元周围(例如 applyDiscounts、chargeProvider)添加手动 span,并附上 on-call 会用来过滤的 attributes。让 context 跨越每一个 async 边界传播——HTTP header、队列消息 metadata——否则 trace 会在断点处死掉。默认以低比例做 head-based 采样;如果你的后端支持 tail sampling,对错误保留 100%。
6. 告警
对用户能感受到的症状告警,不是对原因:
SYMPTOM (page-worthy): CAUSE (dashboard, not a page):
error rate > 1% for 5 min CPU at 85%
p99 latency > 2s one pod restarted
queue age > 10 min disk at 70%
基于原因的告警会在什么都没出错时开火,并错过你没预测到的故障。基于症状的告警恰好在用户受到伤害时开火,无论原因是什么。
对你创建的每条告警的规则:
- 它必须可行动。 如果响应是“忽略它,它会自愈”,删掉这条告警。
- 它链接到一个 runbook——哪怕只有三行:它意味着什么、第一个该跑的查询、升级路径。
- 它有一个阈值和持续时间,依据是 SLO 或历史数据,不是拍脑袋。
- 只用两个严重级别:page(面向用户,立即行动)和 ticket(降级,本周内行动)。第三档会变成噪音,教会人们无视一切。
编写 Runbook
上面第 2 条规则要求每条告警都链接到一个 runbook。Runbook 的职责是回答三个问题,并且不需要读者动脑:正在发生什么、先检查什么、如果这解决不了该找谁。存放在 docs/runbooks/,以告警命名。
最小可用 runbook(三行):
# Runbook
Read the complete source ↗