日志最佳实践十二条：让日志既有用又可控

日志最佳实践是一套让日志"信息充分、成本可控、对系统影响最小"的方法论，核心是解决三个问题：记什么、怎么记、如何管。 开发中最大的难题是事前无法预知哪些信息在排障时至关重要，于是很多团队选择"全都记"——结果是日志量爆炸、成本失控、关键信息反而被淹没。以下十二条实践按"该做 / 不该做"组织，按影响力排序。

十二条实践总览

核心要点速览

• 日志的第一原则：先定目标再动手——想清楚日志要为哪个业务/运维目标服务；
• 级别是最基本的信号体系：生产默认 INFO，排障时动态提升，用完调回；
• 结构化（JSON）是所有后续分析的地基；
• 成本控制三板斧：采样、留存策略、错误日志限流；
• 日志回答"发生了什么"，趋势监控交给指标（Metrics）——两者别混用。

一、明确日志目标

打日志前先回答：这个应用的业务目标是什么？需要跟踪哪些关键指标？有了目标，才能判断哪些事件该记日志、哪些该交给指标或链路追踪，避免"什么都记"的噪声日志。

目标很难一次定准，务实的做法是初期适当多记，然后建立定期评审机制：清理过于啰嗦的日志，补齐缺失的上下文。以错误日志为例，目标不是"记录错误"而是"能修复错误"——所以要记下错误详情及其发生前的事件链。

二、正确使用日志级别

级别是最基本的严重程度信号：

• INFO：有业务意义的正常事件
• WARN：可能演变为问题的异常苗头
• ERROR：影响某个操作的可恢复失败
• FATAL：影响整个程序的不可恢复失败
• DEBUG/TRACE：不代表严重程度，代表细节程度，不进生产常态

生产默认 INFO 是常态，但 INFO 的细节往往不足以排障——所以要具备动态调整级别的能力（详见本系列第 10 篇），最好支持按模块/组件粒度调整，排障完记得调回。

观测云落地：级别要在采集链路中被 Pipeline 提取为标准 status 字段，查看器才能着色筛选、监控器才能按级别告警 。

三、结构化日志

自由文本日志机器解析困难，自动化分析无从谈起。三步走：

1. 应用采用支持 JSON 输出的日志框架；
2. 中间件开启结构化输出（如 PostgreSQL 15+ 的 jsonlog、Nginx 的 log_format ... escape=json）；
3. 改不动来源的老系统，交给采集管道在平台侧切割转换。

观测云落地：DataKit 采集 + Pipeline 切割即可完成第三步，无需修改应用代码 。

四、写有信息量的日志

日志的价值取决于信息质量。反面教材：

{"timestamp": "2026-08-25T14:52:43Z", "level": "INFO", "message": "登录失败"}

改进后——能回答"谁、为什么、在哪、哪次请求"：

{
  "timestamp": "2026-08-25T14:52:43Z",
  "level": "INFO",
  "message": "登录失败：密码错误",
  "user_id": "u_12345",
  "source_ip": "192.168.1.25",
  "attempt_num": 3,
  "trace_id": "xyz-request-456",
  "service": "user-auth"
}

写作标准：未来的你（或凌晨三点被叫醒的值班同事）能仅凭这条日志理解发生了什么。可参考 OWASP 的日志字段建议清单补充上下文。

五、日志采样

日产 TB 级日志的系统里，全量留存既不必要也不经济。采样只保留有代表性的子集（如每 5 条相同日志留 1 条），存储与处理成本随之显著下降。采样可以在应用框架内实现，也可以在采集管道层完成；错误日志突发风暴时尤其有效。详见本系列第 16 篇。

六、每请求一条标准日志行（Canonical Log Line）

在每个请求结束时输出一条汇总日志，包含这次请求的全部关键信息：入参摘要、调用方身份、数据库查询次数、耗时、限流计数、响应状态等。

{
  "method": "POST", "path": "/user/login", "request_id": "req_98765",
  "status": 500, "user_id": "u_789", "service": "auth",
  "duration_ms": 320, "db_time_ms": 120
}

排障时你只需看这一条日志就能掌握请求全貌，而不必从十几条碎片日志中拼图。

七、聚合与集中

微服务环境下，日志分散在多台机器与多个服务中，必须集中到统一平台，才能跨服务关联事件、加速根因定位。观测云落地：DataKit 采集（磁盘文件/容器 stdout/远程推送/Sidecar）汇入工作空间，查看器一站检索 。

八、配置留存策略

日志平台的成本通常与"摄入量 × 留存时长"挂钩。按日志类别设定差异化留存：排障热数据短留存，审计日志归档。观测云落地：多索引 + 差异化存储策略（标准/低频/归档），到期自动清理；需要长期留存的经数据转发归档到对象存储 。同时别忘记应用主机上的日志轮转（logrotate），防止磁盘写满。

九、访问控制与加密

数据库日志等常含敏感信息，必须确保传输与存储加密、按角色授权访问、访问行为留审计。观测云落地：数据访问按角色限定查询范围，字段展示权限控制敏感字段可见性 。

十、不记录敏感数据

Twitter 与 GitHub 都曾因密码误入内部日志而大规模整改。原则：敏感数据从源头就不该进入日志；必须引用时用脱敏或令牌化。三层防线：应用内控制对象输出字段（如 Go slog 的 LogValuer 接口）→ 管道层 Pipeline 脱敏 → 平台层敏感数据扫描兜底。详见本系列第 15 篇。

十一、别忽视日志的性能开销

日志不是免费的：实测中，同一个 Go HTTP 服务不打日志约 19 万 QPS，换用不同日志库后性能下降幅度从 3% 到 20% 不等——框架选型直接决定开销。缓解手段：选高性能框架、异步写盘、采样、峰值压测验证磁盘承载力。

十二、别拿日志当监控用

日志只记录预定义的事件，不适合做趋势分析与异常检测。"每秒请求数、错误率、延迟"这类问题应交给指标（Metrics）回答——指标轻量、连续、适合聚合与告警。日志负责"发生了什么"，指标负责"趋势如何"，各司其职。

总结

十二条实践可以浓缩成一句话：带着目标结构化地记、按级别有节制地记、集中起来安全地管、用采样和留存控制成本。实践不是一次到位，定期评审日志质量才能让体系持续健康。

常见问题（FAQ）

Q：十二条里最先落地哪几条？
优先做第 2、3、7 条（级别、结构化、集中化）——它们是其余一切的地基；成本出现压力时再做采样与留存策略。

Q：日志采样会不会丢掉关键错误信息？
合理策略下不会：对 ERROR/FATAL 不采样或高保留率，只对健康检查、访问日志等高频低价值日志采样。

Q：日志轮转和平台留存策略是一回事吗？
不是。轮转是应用主机本地的文件管理（防止磁盘写满）；留存策略是日志平台上的数据生命周期管理。两者都需要。

---

系列阅读：日志格式化最佳实践 ｜ 降低日志成本七步法