4. 结构化日志定义：JSON vs 文本日志，结构化日志Schema设计

在可观测性体系中，日志是记录系统状态与行为最原始、最丰富的信号。然而，传统文本日志（如 Apache 通用日志格式、Syslog）在机器解析、字段检索、跨系统关联方面存在天然缺陷。本节将深入对比 JSON 与文本日志的差异，并给出面向租户隔离场景的结构化日志 Schema 设计规范。

4.1 JSON vs 文本日志：核心差异对比

4.2 结构化日志 Schema 设计

一个健壮的结构化日志 Schema 应遵循“必选字段保证可操作性，可选字段丰富上下文，扩展字段支持业务定制”的三层设计原则。以下 Schema 面向多租户可观测性场景，兼顾通用性与租户隔离需求。

4.2.1 必选字段（Mandatory Fields）

必选字段是每条日志记录必须携带的元数据，缺失将导致日志无法被正确路由、索引或关联。建议在日志框架层（如 Logback、Serilog、log4j2）通过全局配置自动注入。

4.2.2 可选字段（Optional Fields）

可选字段在特定场景下提供额外上下文，缺失不影响日志的基本可观测性。建议在日志产生时按需填充，避免过度采集导致存储膨胀。

4.2.3 扩展字段（Extension Fields）

扩展字段以 ext_ 前缀命名，用于承载业务特定数据或临时调试信息。扩展字段不应被索引系统强制解析，建议使用 object 类型包裹，避免字段爆炸。

{
  "ext_business": {
    "order_id": "ORD-20250321-12345",
    "payment_channel": "wechat",
    "coupon_id": "CPN-999"
  },
  "ext_debug": {
    "cache_hit": true,
    "db_query_count": 3
  }
}

4.3 日志序列化与反序列化

序列化（Serialization）指将内存中的日志对象转换为 JSON 字符串的过程；反序列化（Deserialization）则是将 JSON 字符串还原为日志对象。在多租户高吞吐场景下，序列化性能直接影响应用吞吐量。

4.3.1 序列化最佳实践

• 使用专用日志序列化器：避免在业务线程中直接调用 ObjectMapper.writeValueAsString()，应使用日志框架内置的 Layout（如 Logback 的 JsonLayout、Log4j2 的 JsonTemplateLayout），它们经过异步优化，减少对业务线程的阻塞。
• 固定字段顺序：将必选字段（如 @timestamp、level、tenant_id）放在 JSON 对象前部，便于日志收集器快速解析路由字段，无需扫描整个对象。
• 避免序列化循环引用：日志对象中若包含循环引用的实体（如双向关联的 ORM 对象），必须使用 @JsonIgnore 或 DTO 转换，否则会导致 StackOverflowError。
• 控制单条日志大小：建议单条 JSON 日志不超过 10 KB，超过部分应截断或拆分。过大的日志（如包含完整 HTTP Body）会阻塞 I/O 管道，影响整体吞吐。

4.3.2 反序列化与日志消费

在日志消费端（如 Logstash、Fluentd、Kafka Consumer），反序列化需关注以下要点：

• 宽松解析模式：开启 JSON 解析器的 allowComments、allowTrailingCommas 等宽松选项，避免因格式不严格导致整条日志丢弃。
• 字段类型安全：对于 duration_ms 等数字字段，若序列化时误输出为字符串 "235"，消费端应支持自动类型转换或显式映射。
• 租户路由：反序列化后优先提取 tenant_id 字段，用于将日志路由到对应租户的索引或存储分区，实现读写隔离。

// Java 示例：使用 Logback JsonLayout 输出结构化日志
<appender name="JSON_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
  <file>logs/app.json</file>
  <encoder class="ch.qos.logback.classic.encoder.JsonEncoder">
    <!-- 自定义字段映射 -->
    <customFields>{"tenant_id":"${TENANT_ID}","service.name":"order-service"}</customFields>
  </encoder>
  <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
    <fileNamePattern>logs/app.%d{yyyy-MM-dd}.json</fileNamePattern>
  </rollingPolicy>
</appender>

4.4 结构化日志 Schema 设计总览

4.5 完整日志示例

以下是一个符合上述 Schema 的完整 JSON 日志示例，涵盖必选、可选、扩展三层字段：

{
  "@timestamp": "2025-03-21T14:30:00.123+08:00",
  "level": "ERROR",
  "logger": "com.example.order.OrderService",
  "message": "订单支付失败，余额不足",
  "tenant_id": "tenant-abc-001",
  "service.name": "order-service",
  "trace_id": "abc123def456",
  "span_id": "span-789",
  "user_id": "user-888",
  "request_id": "req-20250321-001",
  "duration_ms": 235,
  "http.method": "POST",
  "http.status_code": 500,
  "error.stack_trace": "java.lang.ArithmeticException: / by zero\n\tat com.example.order.OrderService.pay(OrderService.java:120)",
  "ext_business": {
    "order_id": "ORD-20250321-12345",
    "payment_channel": "wechat"
  },
  "ext_debug": {
    "cache_hit": false,
    "db_query_count": 3
  }
}