如何统一日志规范
统一日志规范的核心在于建立一套全团队必须遵守的日志标准协议，明确日志的格式、级别、字段、输出方式和命名规则。以下是具体的实施指南：
一、 统一日志格式与关键字段
推荐使用 JSON 格式 输出日志，因其结构化、易于解析且机器友好。一条标准的日志应包含以下核心字段：
| 字段名 | 含义 | 示例 |
|---|---|---|
timestamp |
ISO8601标准时间戳 | 2023-10-27T10:00:00.000+08:00 |
level |
日志级别（大写） | INFO, ERROR |
service_name |
服务或应用名 | user-service |
trace_id |
链路追踪ID（用于串联请求） | a1b2c3d4... |
message |
简洁的日志描述 | 用户登录成功 |
exception |
异常堆栈（仅Error级别） | {...} |
示例（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 导致日志噪音。
- ERROR（错误）：必须处理。系统无法继续运行或核心流程中断（如数据库崩溃、支付失败）。需触发告警。
- WARN（警告）：注意但无需立即处理。潜在问题（如请求参数不合法、重试机制触发、缓存击穿）。
- INFO（信息）：记录关键业务节点。系统运行状态、重要操作（如用户下单、登录成功、定时任务启动）。
- 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天），防止磁盘爆满。
五、 落地与执行策略
- 编写《日志规范文档》：将上述规则文档化，作为新人入职必读和代码评审（Code Review）的依据。
- 统一技术栈：在团队内统一日志框架（Java 推荐 Logback 或 Log4j2，Go 推荐 Zap 或 Logrus），并封装统一的日志工具类（Logger），强制注入
trace_id等公共字段。 - 代码评审（CR）卡点：在 Code Review 中检查日志是否合规，特别是异常处理是否打印了堆栈，以及是否包含关键业务参数。
- 自动化检测：利用 SonarQube 或自定义 Lint 规则，检测代码中是否存在
System.out.println或字符串拼接日志等违规写法。
六、 进阶：日志与监控联动
规范统一后，日志的价值在于分析。建议接入 ELK (Elasticsearch, Logstash, Kibana) 或 Loki 进行集中采集。通过规范中的 level 和 service_name 字段，可以快速构建监控大盘，例如统计每分钟的 ERROR 日志数量，或针对特定 trace_id 进行全链路日志检索。