← 中文资源

简体中文版本

添加结构化 JSON 日志

用携带 request id、状态、延迟和脱敏请求头的结构化 JSON 日志替代临时 console 输出,支持可靠的生产排查。

阅读英文原文

记录事件,而不是句子

结构化日志是带字段的事件,而不是需要用正则解析的句子。requestId、route、status 和 durationMs 可以被索引和聚合。字段名要保持稳定;重命名 durationMs 即使值仍在另一个键下,也会破坏仪表盘和告警。

{"level":30,"service":"orders-api","requestId":"6f1c...","method":"GET","route":"/orders/:id","status":200,"durationMs":12,"msg":"request completed"}

在源头脱敏

在 logger 中配置脱敏,而不只在调用点。新开发者可能不假思索地记录 req.headers。logger 应确定性地移除 authorization、cookie 等敏感字段。即使生产 debug 级别,也绝不记录请求体、密码或令牌。

控制日志量

每个请求在 info 级别记录一个完成事件。详细诊断放在 debug 级别,并在高流量下采样。完整 URL、用户输入和原始错误消息等高基数字段会撑爆存储并暴露个人数据。错误应通过处理器在服务端记录堆栈,并向客户端返回通用消息。

验证输出

预期结果:每个完成请求产生一行可解析 JSON,其 requestId 与响应头 x-request-id 一致,且没有任何行包含 authorization 或 cookie 值。用 jq 和手动搜索 [REDACTED] 确认。任一检查失败,都应在部署前修复 logger。