如何统一日志规范

统一日志规范的核心在于建立一套全团队必须遵守的日志标准协议，明确日志的格式、级别、字段、输出方式和命名规则。以下是具体的实施指南：

一、 统一日志格式与关键字段

推荐使用 JSON 格式 输出日志，因其结构化、易于解析且机器友好。一条标准的日志应包含以下核心字段：

示例（JSON格式）：

{
  "timestamp": "2023-10-27T10:00:00.000+08:00",
  "level": "ERROR",
  "service": "payment-service",
  "trace_id": "abc-123-xyz",
  "message": "支付回调处理失败",
  "user_id": "10001",
  "error_detail": "Connection timeout"
}

二、 明确日志级别（Log Levels）

严格定义各级别的使用场景，防止滥用 ERROR 或乱打 DEBUG 导致日志噪音。

1. ERROR（错误）：必须处理。系统无法继续运行或核心流程中断（如数据库崩溃、支付失败）。需触发告警。
2. WARN（警告）：注意但无需立即处理。潜在问题（如请求参数不合法、重试机制触发、缓存击穿）。
3. INFO（信息）：记录关键业务节点。系统运行状态、重要操作（如用户下单、登录成功、定时任务启动）。
4. DEBUG（调试）：开发环境专用。详细的逻辑变量、参数信息，生产环境默认关闭。

三、 制定日志内容规范

• TraceId 全链路透传：在微服务架构中，确保每个请求入口生成 trace_id，并在 RPC 调用、MQ 发送时透传，这是排查跨服务问题的唯一线索。
• 敏感信息脱敏：严禁在日志中打印明文密码、身份证号、手机号、银行卡号等。必须进行掩码处理（如 138****0000）。
• 参数化日志：使用占位符而非字符串拼接，避免不必要的字符串构造开销，并防止日志注入攻击。
  • 推荐：log.info("用户 {} 查询订单 {}", userId, orderId);
  • 禁止：log.info("用户 " + userId + " 查询订单 " + orderId);

四、 命名与输出规范

• 日志文件命名：建议采用 服务名-日志类型-日期.log 格式，例如 user-service-app-2023-10-27.log 或 user-service-error-2023-10-27.log。
• 输出位置：统一输出到标准输出（Stdout）或固定的日志目录（如 /var/log/app/），便于容器化部署和采集。
• 滚动策略：限制单文件大小（如 100MB）和保留天数（如 7天），防止磁盘爆满。

五、 落地与执行策略

1. 编写《日志规范文档》：将上述规则文档化，作为新人入职必读和代码评审（Code Review）的依据。
2. 统一技术栈：在团队内统一日志框架（Java 推荐 Logback 或 Log4j2，Go 推荐 Zap 或 Logrus），并封装统一的日志工具类（Logger），强制注入 trace_id 等公共字段。
3. 代码评审（CR）卡点：在 Code Review 中检查日志是否合规，特别是异常处理是否打印了堆栈，以及是否包含关键业务参数。
4. 自动化检测：利用 SonarQube 或自定义 Lint 规则，检测代码中是否存在 System.out.println 或字符串拼接日志等违规写法。

六、 进阶：日志与监控联动

规范统一后，日志的价值在于分析。建议接入 ELK (Elasticsearch, Logstash, Kibana) 或 Loki 进行集中采集。通过规范中的 level 和 service_name 字段，可以快速构建监控大盘，例如统计每分钟的 ERROR 日志数量，或针对特定 trace_id 进行全链路日志检索。