一条有用的日志，应该留下什么

“请求失败了”告诉我们结果，却没有留下足够的线索。真正有帮助的日志，应当让后来的人知道发生了什么、发生在哪一步，以及如何把相关事件串起来。

01 / 先写事件，再写形容词

与其记录一串“开始了”“出错了”，不如给事件一个稳定名称，再附上必要字段。下面是一个虚构的业务事件，数值仅用于说明格式：

{
  "level": "warn",
  "event": "document.fetch_failed",
  "request_id": "demo-42",
  "duration_ms": 1208,
  "attempt": 2,
  "error_code": "UPSTREAM_TIMEOUT"
}

稳定的字段便于搜索与聚合。duration_ms 把单位放进名称，attempt 说明重试位置；它们比一句“请求很慢”更容易核对。字段的选择来自要回答的问题，不必为每条日志附上所有数据。

02 / 让一次请求有一条线索

当一个操作经过多个函数或服务时，可以传递同一个请求标识，把相关事件连起来。它帮助我们从一条失败记录回到前面的步骤，而不用仅凭时间接近来猜测。

也要区分预期中的分支与需要处理的异常。例如，主动取消操作和服务无法响应，通常值得保留不同的事件名称。日志等级应当与实际处理方式一致，避免让普通情况淹没真正需要关注的信号。

03 / 留下证据，也保持克制

调试时最顺手的“把整个对象打印出来”，也最容易把密码、令牌或个人信息带进日志。记录前先挑选字段；需要保留的敏感值，应根据用途删除、脱敏或采用合适的保护措施。

输入文本可能含有换行等控制字符。使用结构化日志工具，正确编码字段，避免一段用户输入看起来像额外生成了一条可信的系统记录。