以“用户刚刚无法完成付款”为例，排查至少需要知道：请求是否到达、哪个版本在运行、支付事件是否被处理，以及权限是否已经更新。可观测性就是为这类问题保留可查询的记录。
本文适合正在接入第一套日志、指标和追踪的小团队。OpenTelemetry 将常用遥测信号归纳为 traces、metrics 和 logs；它们分别用于还原请求路径、观察聚合变化和保存离散事件。官方概览可帮助理解术语。告警已经出现后的处理顺序，见《告警响起后：小团队如何确认影响并恢复服务》。
选择一条用户路径
列出产品最重要的三到五个任务，例如注册、登录、创建项目、完成支付、导出数据。每个任务只回答：成功了吗、用了多久、失败在哪里、影响了多少人。
这会产生比“CPU、内存、请求数”更直接的初始指标：
| 任务 | 成功信号 | 失败信号 | 关联标识 |
|---|---|---|---|
| 登录 | 会话创建完成 | 身份服务拒绝、验证码过期 | requestId、匿名用户 ID |
| 创建项目 | 数据已持久化 | 校验、配额、依赖超时 | requestId、projectId |
| 支付同步 | 权益投影已更新 | 签名失败、重复事件、对账差异 | eventId、subscriptionId |
关联标识应当能跨越入口、队列和下游调用；但不要把邮箱、令牌、完整 URL 参数或请求正文当作 trace ID 写入日志。
让日志可以查询
自由文本日志在故障时很难聚合。最小结构化字段可包括时间、等级、服务/版本、事件名、requestId、耗时、错误类别和安全的资源标识：
{"event":"invoice_sync_failed","level":"error","requestId":"req_...","kind":"signature_invalid","release":"2026.09.02-1"}错误类别比完整错误信息更稳定：validation_failed、dependency_timeout、rate_limited、signature_invalid。保留足够上下文帮助定位，但在写入前审查密码、Cookie、授权头、支付数据和用户文本。日志保留期与访问权限也属于隐私设计的一部分。
选择少量指标和告警
从每个关键任务挑一个成功率、一个延迟和一个积压/容量信号。只对需要你采取行动的指标设告警：
- 连续失败而非单个偶发错误；
- 队列积压持续增长而非一次短峰值；
- 关键依赖不可用且已有用户影响；
- 证书临近过期、域名解析异常等有明确处理窗口的事件。
告警应该写明行动：“检查支付事件签名配置与上游状态”“暂停新任务并查看队列消费者”，而非只给一个红色数字。若凌晨收到后无法采取动作，它应该是工作时间报告，不是即时告警。
让错误关联到版本和影响
给每次发布附上版本标识，错误事件就能回答“这是否只发生在新版本”。用户反馈页、客服工单和错误追踪之间使用同一个安全关联号；未经同意不要把完整用户会话录屏或敏感输入自动上传。
新错误上线时，先看发生频率、受影响任务、首发版本和是否可重现；不要按堆栈数量排序后逐个修。一个频繁的配置错误可能比十个罕见边缘错误更值得优先处理。
为跨服务请求保留追踪路径
当一个请求跨 API、数据库、队列和第三方服务时，单条日志只能看到碎片。分布式 trace 的作用是将同一请求的 span 关联成路径；OpenTelemetry 的可观测性入门说明了 trace、span 与属性的关系。
不要在每个函数创建 span。先覆盖 HTTP 入口、关键数据库/队列操作和外部调用，统一携带 request ID，再根据真实故障补点。测量本身有成本，采样策略与数据脱敏应和产品规模一起演进。
为告警准备运行手册
运行手册可以只是几行 Markdown：影响是什么、先看哪个仪表盘/日志、如何区分常见原因、何时升级、临时缓解方式。它的目标不是替代判断，而是在紧急时避免重复试错。
将发布、回滚与告警连在一起，详见《发布与回滚：先设计停止条件，再改生产环境》。排查跨地域网络现象时，先记录节点、时间、协议层证据，再归因，详见《Asia DevTools 当前的边界：本地工具、排查笔记与计划中的网络检查》。
从一次超时整理可复查记录
只有“页面很慢”的描述，还不足以确定下一步从哪里查。下面使用与本站模拟记录相同的虚构材料，练习把实际观察和未知事实分开：
模拟客户端 A / 测试环境 / 示例版本 v1
模拟时间：2026-09-07 09:05 +08:00
GET /items：客户端等待 3000ms 后中止。
未取得 HTTP 状态。
服务端是否完成：未知。
对照：相同客户端 GET /health，200，150ms。这个对照说明另一条请求的观察结果，不能据此判断 /items 已经成功或失败，也不能把客户端中止写成 HTTP 504。AbortController 提供的是中止信号及相关 API 的响应机制；据此不能确认服务端工作已经结束。WHATWG DOM 标准说明了该机制（复核于 2026-09-07）。如果确实收到 504，它表示网关或代理没有及时取得所需上游响应，仍不能单凭状态码判定数据库故障。RFC 9110定义了这一状态（复核于 2026-09-07）。
打开排查记录，在空记录中点“填入模拟记录”，再核对三个必填项：
| 字段 | 这组材料应表达什么 |
|---|---|
| 想完成的操作 | 模拟练习：读取商品列表 |
| 实际观察 | 客户端等待 3000ms 后中止、未取得 HTTP 状态、服务端是否完成未知 |
| 下一步复查 | 保持相同客户端、环境和请求条件，先按发生时间核对服务端是否收到请求，再记录复查结果 |
展开可选项查看时间、环境、预期、对照和未知项。“复查结果”尚未填写，导出后应保持“未知（未填写）”。如果只填写自己的材料，先保证三个必填项足以说明任务，再逐步补证据；没有取得的事实可以留空。模拟记录不会覆盖已有输入，需要先自行保存并清空后才能填入。
点击“生成排查记录”并核对 Markdown。正确的产物应同时保留客户端中止、HTTP 状态未知和服务端完成情况未知，而不是生成一个根因结论。复制失败时可手动选择文本或下载 diagnostic-record.md；内容仅留当前页面，离开或刷新前确认自己已经保存。记录不会自动提交给本站或发送给协作者。
补充证据后怎样复查
按时间、版本和经过审查的关联号核对入口与上游记录，记下实际改变了什么；未取得材料仍写未知。只看到一次成功时，记录该次条件与结果，不将其扩大为整体恢复。写入操作重试前先核对执行结果与幂等策略；取证顺序见 API 请求超时指南和故障取证指南。
回到记录的“已做修改”和“复查结果”补充新事实。编辑后旧结果立即失效，需重新生成并下载；当前能带走的是一份可继续核对的记录，不是本站验证通过的报告。若仍缺入口记录，这一步的合理终点就是说明缺什么、由谁在什么环境继续核对。
分享前逐项检查认证、Cookie、用户正文和私人标识；本站不会自动脱敏。若反馈的是本站工具缺陷，再使用空白复现模板，以虚构输入重现并自行检查后联系。普通业务排查无需发送给本站。
若证据指向发布后仍看到旧内容，可按域名切换后的复查方法核对解析、缓存与正文版本。本地缓存文本工具只整理支持字段，不测量缓存命中、超时原因或地区可用性。
接入清单
- 三到五条关键用户任务都有成功、延迟和失败分类。
- 日志可按 requestId、版本和错误类别查询，且不含密钥与敏感正文。
- 即时告警数量少、每条都有明确行动。
- 错误事件可关联到发布版本与安全的用户反馈记录。
- 关键链路具备有限、脱敏的 trace 路径。
- 每次事故后更新一个指标、运行手册或检查，而不只是“多看一眼”。
最好的监控系统不会让你永远不出故障；它让你在故障发生时更快停止猜测。