日志工程基础：日志分类、级别与格式规范

日志是系统可观测性的基石。在构建冷热分离架构之前，必须统一日志的分类、级别与格式标准。混乱的日志不仅增加存储成本，更会在故障排查时引入大量噪音。本节从三个维度建立日志工程的基础规范。

2.1 日志分类

根据日志的来源与用途，通常划分为三类：业务日志、系统日志与审计日志。三类日志在冷热分离架构中的保留策略与查询频率差异显著。

2.2 日志级别

日志级别定义了日志的严重程度与响应优先级。统一级别标准是后续告警规则与日志采样策略的前提。推荐采用业界通用的 Syslog 级别 或 SLF4J 级别，并严格限制生产环境中 DEBUG 级别的输出量。

• FATAL / CRITICAL：系统不可用，需立即人工介入。例如：数据库连接池耗尽、主进程崩溃。
• ERROR：功能不可用，但系统可继续运行。例如：第三方接口超时、数据校验失败。
• WARN：异常行为，但不影响当前请求。例如：磁盘使用率超过80%、重试次数超过阈值。
• INFO：关键业务节点记录。例如：订单创建成功、用户登录。
• DEBUG：开发与排障使用，生产环境默认关闭或按需动态开启。
• TRACE：细粒度跟踪，仅用于分布式链路追踪的本地调试。

2.3 日志格式规范：JSON 结构化

非结构化日志（如纯文本、空格分隔）在冷热分离架构中难以被高效解析、路由与压缩。必须采用 JSON 结构化格式，确保每个日志事件包含统一的元数据字段。

2.3.1 标准字段定义

2.3.2 示例：标准 JSON 日志行

{
  "timestamp": "2025-03-21T14:30:00.123Z",
  "level": "ERROR",
  "logger": "com.order.service.PaymentHandler",
  "message": "Payment timeout after 3 retries",
  "trace_id": "abc123def456",
  "span_id": "span-789",
  "service": "payment-service",
  "host": "node-01",
  "env": "production",
  "extra": {
    "order_id": "ORD-20250321-001",
    "amount": 299.99,
    "retry_count": 3
  }
}

2.4 日志分类与格式关系图

下图展示了三类日志在采集、结构化与冷热存储路径中的流转关系。

2.5 日志格式规范检查清单

在接入日志采集管道前，建议逐项检查以下规范是否落地：

1. 字段完整性：所有日志是否包含 timestamp、level、service、trace_id 四个必选字段。
2. 时间格式统一：是否全部使用 ISO 8601 格式，且时区统一为 UTC。
3. JSON 合法性：每条日志是否为合法的 JSON 对象，无尾随逗号、无多行嵌套。
4. 敏感数据过滤：是否已配置脱敏规则，避免身份证、银行卡号等明文出现。
5. 级别使用规范：生产环境是否关闭 DEBUG 级别输出，ERROR 级别是否对应明确的告警规则。
6. 日志分类标签：是否在 extra 字段中标记 log_category（business / system / audit），便于后续冷热路由。