附加：异步日志聚合

---

异步日志聚合详细示例与解释

在异步或多线程场景中，日志聚合的关键在于确保同一请求链路的日志能通过唯一标识（如 traceId）关联。以下通过完整示例展示如何在异步任务中传递 traceId，并结合日志配置和实际代码，实现跨线程的日志聚合追踪。

---

1. 场景描述

假设有一个订单处理服务，主线程接收请求后，提交异步任务到线程池执行。需确保主线程和异步任务的日志共享相同的 traceId，便于后续在日志系统中通过 traceId 聚合所有相关日志。

---

2. 完整代码实现

2.1 主线程设置 traceId

在请求入口（如HTTP请求过滤器）生成并设置 traceId：

import org.slf4j.MDC;
import javax.servlet.*;
import java.io.IOException;
import java.util.UUID;

public class TraceIdFilter implements Filter {
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
        // 生成唯一 traceId（实际可从请求头获取）
        String traceId = UUID.randomUUID().toString();
        MDC.put("traceId", traceId);
        
        try {
            chain.doFilter(request, response);
        } finally {
            MDC.clear(); // 请求处理完成后清理
        }
    }
}

2.2 异步任务传递 traceId

提交异步任务时，手动复制主线程的 MDC 上下文：

import org.slf4j.MDC;
import java.util.Map;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

public class OrderService {
    private static final Logger logger = LoggerFactory.getLogger(OrderService.class);
    private final ExecutorService executor = Executors.newFixedThreadPool(2);

    public void processOrderAsync(String orderId) {
        // 获取当前线程的 MDC 上下文
        Map<String, String> context = MDC.getCopyOfContextMap();
        
        executor.submit(() -> {
            // 将主线程的 MDC 上下文注入子线程
            if (context != null) {
                MDC.setContextMap(context);
            }
            
            try {
                logger.info("开始处理订单: {}", orderId); // 日志包含 traceId
                // 业务逻辑...
                logger.info("订单处理完成: {}", orderId);
            } finally {
                MDC.clear(); // 清理避免污染后续任务
            }
        });
    }
}

2.3 日志配置文件（logback.xml）

配置日志格式，包含 %X{traceId} 以输出 MDC 中的值：

<configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] [%X{traceId}] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>
    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>

---

3. 示例输出与解析

3.1 日志输出示例

2024-03-20 14:30:45 [http-nio-8080-exec-1] [c257d4e3] INFO  com.example.OrderService - 收到新订单: ORDER_1001
2024-03-20 14:30:45 [pool-1-thread-1] [c257d4e3] INFO  com.example.OrderService - 开始处理订单: ORDER_1001
2024-03-20 14:30:46 [pool-1-thread-1] [c257d4e3] INFO  com.example.OrderService - 订单处理完成: ORDER_1001

关键点：

• traceId 一致性：主线程（http-nio-8080-exec-1）和异步线程（pool-1-thread-1）的日志共享相同的 traceId（c257d4e3）。
• 日志聚合：在日志系统中筛选 traceId=c257d4e3，可查看该订单处理的全链路日志。

---

4. 实现原理详解

4.1 MDC 上下文传递

• 主线程：在请求入口（如过滤器）通过 MDC.put("traceId", traceId) 设置上下文。
• 异步任务：
  • 提交任务前，通过 MDC.getCopyOfContextMap() 复制主线程的 MDC 数据。
  • 在异步任务执行前，通过 MDC.setContextMap(context) 将上下文注入子线程。

4.2 线程池的风险与防御

• 风险：线程池中的线程会被复用，若未清理 MDC，后续任务可能误用前一个任务的 traceId。
• 防御：在异步任务的 finally 块中调用 MDC.clear()，确保线程归还到池时无残留数据。

4.3 日志格式配置

• %X{traceId}：在日志模板中插入 MDC 中的 traceId 值。
• 线程安全：MDC 内部使用 ThreadLocal 存储数据，天然支持多线程隔离。

---

5. 高级优化：自动传递上下文的线程池

通过装饰器模式封装线程池，自动处理 MDC 上下文的传递与清理，减少重复代码。

5.1 自定义线程池装饰器

import org.slf4j.MDC;
import java.util.Map;
import java.util.concurrent.*;

public class MdcAwareExecutor implements Executor {
    private final Executor delegate;

    public MdcAwareExecutor(Executor delegate) {
        this.delegate = delegate;
    }

    @Override
    public void execute(Runnable command) {
        // 捕获当前线程的 MDC 上下文
        Map<String, String> context = MDC.getCopyOfContextMap();
        delegate.execute(() -> {
            // 任务执行前注入 MDC
            if (context != null) {
                MDC.setContextMap(context);
            }
            try {
                command.run();
            } finally {
                MDC.clear();
            }
        });
    }
}

5.2 使用示例

// 创建原生线程池
ExecutorService rawExecutor = Executors.newFixedThreadPool(2);
// 包装为支持 MDC 的线程池
ExecutorService mdcExecutor = new MdcAwareExecutor(rawExecutor);

// 提交任务（自动传递上下文）
mdcExecutor.execute(() -> {
    logger.info("异步任务执行");
});

---

6. 常见问题与解决

问题	解决方案
日志中缺失 traceId	检查 logback.xml 的 pattern 是否包含 %X{traceId}，确认 MDC 设置正确。
异步任务间 traceId 串扰	确保每次任务执行后调用 MDC.clear()，或使用线程池装饰器自动清理。
高并发下 traceId 不一致	使用线程安全的 UUID 生成算法（如 UUID.randomUUID()），避免重复。

---

7. 日志聚合工具链整合

将日志输出到集中式系统（如 ELK、Splunk），通过 traceId 快速关联日志：

1. 日志收集：使用 Filebeat 或 Logstash 采集应用日志。
2. 存储与索引：在 Elasticsearch 中按 traceId 建立索引。
3. 可视化查询：通过 Kibana 输入 traceId:c257d4e3，查看全链路日志。

---

总结

通过 MDC 传递 traceId 并结合日志配置，可实现异步日志的高效聚合：

1. 设置上下文：在请求入口生成 traceId，通过 MDC 绑定到当前线程。
2. 跨线程传递：手动复制或通过装饰器线程池自动传递 MDC 上下文。
3. 日志格式化：配置日志模板输出 traceId。
4. 集中化分析：结合日志聚合工具，实现全链路追踪。

此方案不仅适用于异步任务，还可扩展至微服务间的调用追踪（如在 HTTP 头中传递 traceId），是构建可观测性系统的基石。