3. 结构化日志设计：JSON格式日志、日志字段标准化与上下文传递

在缺陷定位实践中，非结构化的纯文本日志（如“用户登录失败”）往往难以被自动化工具解析，也无法在多服务、多线程的复杂调用链中快速关联。结构化日志通过统一的格式和标准字段，将日志从“人类可读”提升为“机器可解析、人类可检索”的工程资产。本节将深入讲解JSON格式日志的设计原则、字段标准化规范以及日志上下文的传递机制。

3.1 JSON格式日志：为什么选择JSON？

JSON（JavaScript Object Notation）因其轻量、自描述、跨语言支持的特性，已成为结构化日志的事实标准。相比纯文本或CSV格式，JSON具有以下优势：

• 自描述性：每个字段都有明确的键名，无需依赖外部文档即可理解日志含义。
• 层次结构：支持嵌套对象和数组，能够表达复杂的业务上下文（如请求体、错误堆栈）。
• 生态丰富：几乎所有日志收集工具（Logstash、Fluentd）、存储系统（Elasticsearch、ClickHouse）和可视化平台（Kibana、Grafana）都原生支持JSON解析。
• 类型保留：数字、布尔值、null等类型在JSON中得以保留，便于进行数值聚合和条件过滤。

以下是一个典型的单行JSON日志示例：

{
  "timestamp": "2025-04-07T14:23:45.123+08:00",
  "level": "ERROR",
  "logger": "com.example.order.OrderService",
  "thread": "http-nio-8080-exec-3",
  "traceId": "a1b2c3d4e5f6g7h8",
  "userId": "user_98765",
  "message": "订单创建失败",
  "error": {
    "type": "BusinessException",
    "code": "ORDER_STOCK_INSUFFICIENT",
    "stackTrace": "com.example.order.OrderService.createOrder(OrderService.java:123)\n..."
  },
  "durationMs": 2345,
  "requestParams": {
    "orderId": "ORD-20250407-001",
    "skuId": "SKU-88888",
    "quantity": 10
  }
}

3.2 日志字段标准化：定义通用字段规范

字段标准化的目标是让团队内所有服务输出的日志遵循同一套字段命名和类型规范。这不仅能降低日志查询的学习成本，还能让跨服务的日志关联成为可能。下表列出了推荐的通用字段及其规范：

3.3 日志上下文传递：在分布式链路中保持字段一致性

在微服务架构中，一个用户请求会跨越多个服务。如果每个服务都独立生成日志，那么当出现故障时，你将很难把不同服务中的日志片段关联到同一个请求上。日志上下文传递正是为了解决这个问题——它确保 traceId、userId 等关键字段能够沿着调用链自动传播。

下图展示了日志上下文在三个微服务之间的传递流程：

实现日志上下文传递的常见技术方案包括：

• HTTP Header 传递：在服务间HTTP调用时，通过自定义Header（如 X-Trace-Id、X-User-Id）传递上下文。网关层负责在入口处生成 traceId，后续服务从请求Header中提取并透传。
• RPC 框架 Attachment：在Dubbo、gRPC等RPC框架中，利用框架提供的隐式参数传递机制（如Dubbo的RpcContext、gRPC的Metadata）传递上下文。
• 消息队列 Header：在使用Kafka、RabbitMQ等消息队列时，将上下文信息放入消息的Header属性中，消费者消费时解析并注入到当前线程的MDC（Mapped Diagnostic Context）中。
• 线程池传递：当使用线程池执行异步任务时，需要手动将父线程的MDC上下文拷贝到子线程中，否则 traceId 会丢失。可以使用 ThreadPoolExecutor 的 beforeExecute 钩子方法或自定义 Runnable 包装器来实现。

3.4 实战：在Java应用中实现结构化日志

以下是一个基于Logback和SLF4J MDC的完整实现示例，展示了如何在Spring Boot应用中输出结构化JSON日志：

步骤1：添加Logstash Logback Encoder依赖

<!-- pom.xml -->
<dependency>
    <groupId>net.logstash.logback</groupId>
    <artifactId>logstash-logback-encoder</artifactId>
    <version>7.4</version>
</dependency>

步骤2：配置logback-spring.xml输出JSON格式

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <appender name="JSON_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>logs/app.json</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>logs/app.%d{yyyy-MM-dd}.json.gz</fileNamePattern>
            <maxHistory>30</maxHistory>
        </rollingPolicy>
        <encoder class="net.logstash.logback.encoder.LogstashEncoder">
            <!-- 自定义字段映射 -->
            <includeContext>false</includeContext>
            <fieldNames>
                <timestamp>timestamp</timestamp>
                <level>level</level>
                <logger>logger</logger>
                <thread>thread</thread>
                <message>message</message>
                <stackTrace>error.stackTrace</stackTrace>
            </fieldNames>
            <provider class="net.logstash.logback.composite.loggingevent.MdcJsonProvider">
                <fieldName>mdc</fieldName>
            </provider>
        </encoder>
    </appender>

    <root level="INFO">
        <appender-ref ref="JSON_FILE"/>
    </root>
</configuration>

步骤3：在Filter中注入MDC上下文

@Component
public class TraceIdFilter implements Filter {
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        HttpServletRequest httpRequest = (HttpServletRequest) request;
        String traceId = httpRequest.getHeader("X-Trace-Id");
        if (traceId == null || traceId.isEmpty()) {
            traceId = UUID.randomUUID().toString().replace("-", "");
        }
        MDC.put("traceId", traceId);
        MDC.put("userId", httpRequest.getHeader("X-User-Id"));
        try {
            chain.doFilter(request, response);
        } finally {
            MDC.clear();
        }
    }
}

步骤4：在业务代码中记录日志

@Service
public class OrderService {
    private static final Logger log = LoggerFactory.getLogger(OrderService.class);

    public Order createOrder(CreateOrderRequest request) {
        log.info("开始创建订单, 用户ID: {}", request.getUserId());
        try {
            // 业务逻辑...
            log.info("订单创建成功, 订单ID: {}", orderId);
            return order;
        } catch (Exception e) {
            log.error("订单创建失败, 原因: {}", e.getMessage(), e);
            throw new BusinessException("ORDER_CREATE_FAILED", e);
        }
    }
}

最终输出的日志将自动包含 traceId 和 userId 字段，如下所示：

{"timestamp":"2025-04-07T14:23:45.123+08:00","level":"INFO","logger":"com.example.order.OrderService","thread":"http-nio-8080-exec-3","mdc":{"traceId":"a1b2c3d4e5f6g7h8","userId":"user_98765"},"message":"开始创建订单, 用户ID: user_98765"}

3.5 结构化日志设计检查清单

在团队推行结构化日志时，可以使用以下清单进行评审和落地：

结构化日志不是一蹴而就的工程，它需要团队在框架层面、业务代码层面和运维工具层面协同推进。但一旦落地，它将为后续的日志分析、告警聚合和故障根因分析提供坚实的数据基础。