2. 结构化日志基础：JSON格式定义、字段规范、日志级别与上下文绑定

在分布式系统中，日志不再是面向开发者的“调试输出”，而是面向可观测性系统的“结构化事件流”。本章将定义结构化日志的核心要素：JSON格式、字段规范、日志级别以及上下文绑定机制，为后续Kafka消息链路的事务边界追踪奠定数据基础。

2.1 JSON格式定义：从文本到事件

传统日志以自由文本形式存在，解析困难且缺乏一致性。结构化日志采用JSON作为标准序列化格式，每条日志对应一个独立的事件对象。以下是一个最小化的结构化日志示例：

{
  "timestamp": "2025-03-21T14:32:10.123Z",
  "level": "INFO",
  "logger": "com.example.order.service",
  "message": "订单创建成功",
  "traceId": "abc-123-def-456",
  "spanId": "span-001"
}

JSON格式带来的核心优势包括：

• 机器可读：无需正则表达式即可被日志收集器（如Filebeat、Fluentd）直接解析。
• 模式灵活：支持嵌套对象和数组，便于表达复杂业务上下文。
• 生态兼容：Elasticsearch、ClickHouse、Kafka Connect等工具原生支持JSON。

2.2 字段规范：必选、可选与业务扩展

为保证跨服务、跨团队的日志一致性，必须定义一套统一的字段规范。下表列出了推荐的字段分类与约束：

2.3 日志级别：语义与使用场景

日志级别不仅是过滤工具，更是事件严重性的语义声明。在Kafka消息链路中，不同级别对应不同的处理策略：

• TRACE：最细粒度的调试信息，仅在开发环境或临时诊断时开启。例如：Kafka消息的序列化前后内容对比。
• DEBUG：开发人员关注的内部状态变化。例如：消费者偏移量提交成功。
• INFO：关键业务事件，正常流程的里程碑。例如：订单创建成功、消息发送到Topic。
• WARN：潜在问题但不影响当前操作。例如：消息重试第一次、消费者处理超时但未超过阈值。
• ERROR：功能受损或数据不一致，需要立即关注。例如：消息反序列化失败、事务回滚。
• FATAL：系统级崩溃，服务无法继续运行。例如：Kafka连接池耗尽、磁盘空间不足。

下表总结了不同级别在Kafka场景下的典型触发条件：

2.4 上下文绑定：MDC与自动注入

在分布式链路中，手动为每条日志添加 traceId 和 spanId 是不现实的。上下文绑定机制通过MDC（Mapped Diagnostic Context）实现自动注入。MDC是日志框架（如Logback、Log4j2）提供的一个线程局部存储区域，用于保存当前线程的上下文数据。

以下是一个典型的MDC绑定流程：

1. 请求进入服务时，从Kafka消息头或HTTP请求头中提取 traceId 和 parentSpanId。
2. 生成新的 spanId，并将 traceId、spanId、parentSpanId 放入MDC。
3. 日志框架在输出日志时，自动从MDC读取这些字段并填充到JSON结构中。
4. 请求处理完毕后，清除MDC中的上下文，避免线程池复用导致上下文污染。

// Java示例：使用MDC绑定上下文
import org.slf4j.MDC;

public class KafkaMessageHandler {
    public void handleMessage(ConsumerRecord<String, String> record) {
        try {
            // 1. 从消息头提取traceId
            String traceId = record.headers()
                .lastHeader("traceId")
                .value().toString();
            String parentSpanId = record.headers()
                .lastHeader("spanId")
                .value().toString();
            String spanId = UUID.randomUUID().toString();

            // 2. 绑定到MDC
            MDC.put("traceId", traceId);
            MDC.put("spanId", spanId);
            MDC.put("parentSpanId", parentSpanId);

            // 3. 业务处理（日志自动携带上下文）
            logger.info("开始处理Kafka消息");
            processOrder(record.value());
            logger.info("消息处理完成");

        } finally {
            // 4. 清理MDC，防止线程池污染
            MDC.clear();
        }
    }
}

下图展示了结构化日志从产生到采集的完整上下文绑定流程：

2.5 日志级别与上下文绑定的协同策略

在Kafka消息链路中，日志级别与上下文绑定需要协同工作，避免产生“噪音日志”或“信息黑洞”。以下是一个推荐的协同策略：

• 入口日志（INFO）：记录消息到达时间、Topic、Partition、Offset，绑定traceId。
• 处理日志（DEBUG/INFO）：记录业务处理的关键步骤，如数据库查询、外部API调用，绑定spanId。
• 异常日志（WARN/ERROR）：记录异常堆栈、重试次数、当前偏移量，绑定parentSpanId以便回溯。
• 出口日志（INFO）：记录消息处理结果、耗时、是否提交偏移量，清除MDC上下文。