日志规范的 5 个实践要点

线上出问题时，日志往往是唯一能还原现场的材料。日志的价值不取决于数量，而取决于「能否在关键时刻说清发生了什么」。以下 5 条实践可以在团队里直接推行。

一、使用结构化日志

尽量输出结构化的键值日志（如 JSON），而不是拼接长字符串：{"user_id":123,"action":"pay","amount":99.9}。结构化日志便于检索、聚合与告警，也不会因为字段顺序或文案变化导致解析失败。纯文本日志只适合人类临时阅读，不适合作为长期的数据源。

二、合理使用日志级别

分级要有一致的语义：DEBUG 用于开发调试，INFO 记录关键业务节点，WARN 表示可恢复的异常，ERROR 表示需要人工介入的失败。常见错误是把大量调试信息打成 INFO，导致生产日志被淹没；或者把所有异常都打成 ERROR，制造大量噪音。级别清晰，告警才有意义。

三、带上排查所需的上下文

一条日志至少要能回答：谁、做了什么、结果如何、关联哪个请求。建议统一携带 traceId 贯穿调用链，并附上关键业务标识（如订单号、用户 ID）。缺少上下文的日志，即使记录了错误，也无法还原问题现场。

四、不在日志里泄露敏感信息

密码、密钥、身份证号、银行卡号、完整的手机号与地址等，严禁出现在日志中。必要时做脱敏或只记录哈希。日志常常被集中采集、长期保存并开放给多个角色查看，一旦泄露，影响范围远大于单个系统。

五、统一格式与采集链路

团队应约定统一的日志字段规范与输出位置，通过标准输出由采集组件统一收集，而不是各写各的文件、各用各的时间格式。统一之后，告警规则、检索语法、看板都能复用，运维成本会显著下降。

小结

好的日志不是为了「看起来记录得很全」，而是为了在故障发生时能快速定位、快速止损。结构化、分级清晰、带上下文、脱敏、统一采集——把这 5 点做好，排查问题就不再靠猜。