logging-best-practices

日志记录最佳实践

应用这些日志记录原则，确保应用和服务具备有效的调试、监控和审计能力。

结构化日志

• 对所有日志输出使用结构化格式（JSON）
• 确保所有日志条目都包含一致的字段
• 让日志便于机器解析，同时保持人类可读
• 使用原生支持结构化输出的日志库
• 避免通过字符串拼接生成日志消息；使用结构化字段

标准日志字段

在每条日志中包含以下字段：

• timestamp：采用 ISO 8601 格式并包含时区
• level：日志严重级别（DEBUG、INFO、WARN、ERROR、FATAL）
• message：对事件的可读描述
• service：服务或应用的名称
• version：应用版本或构建标识符
• trace_id：分布式追踪关联 ID
• span_id：当前 span 标识符
• request_id：请求的唯一标识符

日志级别

始终使用恰当的日志级别：

• DEBUG：供开发使用的详细诊断信息
• INFO：正常的运行事件和状态变更
• WARN：已妥善处理的意外情况
• ERROR：影响当前操作但不影响服务的故障
• FATAL：需要立即处理的严重故障

上下文传播

• 在请求生命周期内的所有日志条目中包含请求上下文
• 在服务边界之间传递 trace ID
• 为用户发起的操作添加用户上下文（匿名化）
• 为领域事件包含相关业务上下文
• 使用 MDC（Mapped Diagnostic Context）或等效机制管理上下文

安全与隐私

• 切勿记录敏感信息（密码、令牌、个人身份信息）
• 必须引用敏感数据时，对其进行掩码或脱敏
• 根据数据敏感程度实施适当的日志访问控制
• 考虑数据保留策略和合规要求
• 审计对敏感系统日志的访问

性能注意事项

• 使用异步日志记录，避免阻塞应用线程
• 对生产环境中的高容量 DEBUG 日志实施采样
• 适当缓冲日志，以平衡延迟与吞吐量
• 监控日志基础设施，及时发现瓶颈
• 为不同环境设置恰当的日志级别

日志聚合

• 将所有服务的日志集中到一个平台
• 在所有服务中使用一致的格式
• 实施日志轮转和保留策略
• 启用全文搜索和筛选功能
• 根据日志设置关键模式的告警

错误日志

• 包含完整的错误上下文：消息、代码、堆栈跟踪
• 记录包装或嵌套异常中的错误链
• 包含相关请求和状态信息
• 避免在不同层重复记录错误
• 记录错误恢复操作及其结果

最佳实践

• 在服务边界处记录日志（入口和出口）
• 包含计时信息，以便进行性能分析
• 记录配置变更和部署
• 编写有助于调试且可采取行动的日志消息
• 定期检查并清理日志，减少噪声

日志消息指南

• 编写清晰、描述性强的消息
• 包含相关标识符（用户 ID、订单 ID 等）
• 避免使用“发生错误”等笼统消息
• 在整个应用中使用一致的术语
• 提供足够的上下文，让人无需额外查询也能理解事件

特定环境的配置

• 开发环境：DEBUG 级别、控制台输出、详细格式
• 预发布环境：INFO 级别、结构化 JSON、完整上下文
• 生产环境：INFO/WARN 级别、结构化 JSON、对 DEBUG 日志进行采样