Spring Boot跨服务调用TraceId传播失败的原因与MDC正确用法

Spring Boot 跨服务调用 TraceId 传播失败的原因与 MDC 正确用法

大家好！今天我们来聊聊Spring Boot微服务架构中，TraceId的传播问题。在复杂的分布式系统中，我们需要追踪一个请求从开始到结束的完整路径，以便进行性能分析、故障排查等。TraceId就像一个贯穿始终的身份证，将一次完整的请求关联起来。然而，TraceId的传播并非总是顺利，今天我们就来深入探讨TraceId传播失败的原因以及如何正确使用MDC来实现高效的TraceId传递。

1. TraceId 传播的重要性

在微服务架构中，一次用户请求通常会经过多个服务。如果没有TraceId，我们就无法将这些分散的请求关联起来，难以定位问题。有了TraceId，我们可以：

• 追踪请求链路： 了解请求经过哪些服务，每个服务的耗时。
• 诊断性能瓶颈： 找出导致请求延迟的服务。
• 定位错误根源： 当请求出错时，可以快速定位到出错的服务。
• 监控系统健康： 通过TraceId可以统计请求的成功率、平均响应时间等指标。

2. TraceId 传播的常见方式

常见的TraceId传播方式有以下几种：

• HTTP Header： 将TraceId放在HTTP请求头中，服务间通过HTTP调用时传递。
• 消息队列： 将TraceId放在消息头中，服务间通过消息队列进行异步通信时传递。
• MDC (Mapped Diagnostic Context)： 将TraceId存储在MDC中，在同一线程内共享。

今天我们主要讨论基于HTTP Header和MDC的TraceId传播，因为它们是微服务架构中最常用的方式。

3. TraceId 传播失败的常见原因

TraceId传播失败的原因有很多，下面列举一些常见的：

• 遗漏传递： 在服务调用时，忘记将TraceId添加到HTTP Header或者消息头中。
• 命名不一致： 不同服务使用的TraceId Header名称不一致，导致无法识别。
• 线程切换： 在异步任务或者线程池中，MDC中的TraceId丢失。
• 框架兼容性问题： 使用的框架对MDC的支持不完善，导致TraceId无法正确传递。
• 拦截器/过滤器配置不正确： 拦截器/过滤器没有正确地设置或清除MDC中的TraceId。
• 日志配置错误： 日志配置没有正确配置以输出MDC中的TraceId，即使TraceId存在，也无法在日志中看到。

接下来我们将针对这些原因进行详细分析，并提供解决方案。

4. HTTP Header 传递 TraceId 的实现

HTTP Header 传递是最直接的方式。我们需要在请求发出时将TraceId放入Header，并在接收请求时从Header中取出TraceId。

4.1 发起请求时添加 TraceId

可以使用RestTemplate或者WebClient等HTTP客户端，通过拦截器或者过滤器添加TraceId。

示例 (RestTemplate Interceptor):

import org.slf4j.MDC;
import org.springframework.http.HttpRequest;
import org.springframework.http.client.ClientHttpRequestExecution;
import org.springframework.http.client.ClientHttpRequestInterceptor;
import org.springframework.http.client.ClientHttpResponse;

import java.io.IOException;

public class RestTemplateTraceIdInterceptor implements ClientHttpRequestInterceptor {

    private static final String TRACE_ID_HEADER = "X-Trace-Id";

    @Override
    public ClientHttpResponse intercept(HttpRequest request, byte[] body, ClientHttpRequestExecution execution) throws IOException {
        String traceId = MDC.get("traceId");
        if (traceId != null) {
            request.getHeaders().add(TRACE_ID_HEADER, traceId);
        }
        return execution.execute(request, body);
    }
}

配置 RestTemplate:

import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestTemplate;

@Configuration
public class RestTemplateConfig {

    @Bean
    public RestTemplate restTemplate(RestTemplateBuilder builder) {
        return builder.interceptors(new RestTemplateTraceIdInterceptor()).build();
    }
}

4.2 接收请求时获取 TraceId

可以使用HandlerInterceptor或者Filter等方式，从HTTP Header中获取TraceId，并将其放入MDC。

示例 (HandlerInterceptor):

import org.slf4j.MDC;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.util.UUID;

@Component
public class TraceIdInterceptor implements HandlerInterceptor {

    private static final String TRACE_ID_HEADER = "X-Trace-Id";

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        String traceId = request.getHeader(TRACE_ID_HEADER);
        if (traceId == null || traceId.isEmpty()) {
            traceId = UUID.randomUUID().toString();
        }
        MDC.put("traceId", traceId);
        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {
        MDC.remove("traceId");
    }
}

配置 HandlerInterceptor:

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    private final TraceIdInterceptor traceIdInterceptor;

    public WebMvcConfig(TraceIdInterceptor traceIdInterceptor) {
        this.traceIdInterceptor = traceIdInterceptor;
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(traceIdInterceptor);
    }
}

4.3 常见问题和解决方案

问题	原因	解决方案
遗漏传递TraceId	在发起HTTP请求时，忘记将TraceId添加到Header中。	使用RestTemplate或者WebClient的拦截器/过滤器，统一添加TraceId到Header。
Header名称不一致	不同服务使用的TraceId Header名称不一致，导致无法识别。	统一所有服务使用相同的TraceId Header名称，例如X-Trace-Id。
下游服务没有正确处理TraceId	下游服务没有从Header中获取TraceId，并将其放入MDC。	确保所有服务都实现了从Header中获取TraceId并放入MDC的逻辑。

5. MDC (Mapped Diagnostic Context) 的正确用法

MDC是一个线程安全的Map，用于在同一线程内共享数据。在TraceId传播中，我们可以将TraceId放入MDC，然后在日志中使用它。

5.1 将 TraceId 放入 MDC

在接收到请求后，第一时间将TraceId放入MDC。例如，在HandlerInterceptor或者Filter中：

import org.slf4j.MDC;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.util.UUID;

@Component
public class TraceIdInterceptor implements HandlerInterceptor {

    private static final String TRACE_ID_HEADER = "X-Trace-Id";

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        String traceId = request.getHeader(TRACE_ID_HEADER);
        if (traceId == null || traceId.isEmpty()) {
            traceId = UUID.randomUUID().toString();
        }
        MDC.put("traceId", traceId);
        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {
        MDC.remove("traceId");
    }
}

5.2 从 MDC 中获取 TraceId

在需要使用TraceId的地方，从MDC中获取。例如，在日志中：

logback.xml:

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

    <root level="info">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>

5.3 线程切换时的 MDC 处理

这是最容易出错的地方。如果在异步任务或者线程池中使用MDC，需要手动将MDC的内容传递到新的线程中。

示例 (使用Executor):

import org.slf4j.MDC;
import org.springframework.stereotype.Service;

import java.util.Map;
import java.util.concurrent.Executor;

@Service
public class AsyncService {

    private final Executor taskExecutor;

    public AsyncService(Executor taskExecutor) {
        this.taskExecutor = taskExecutor;
    }

    public void executeAsync(Runnable task) {
        Map<String, String> contextMap = MDC.getCopyOfContextMap(); // 获取当前线程的MDC内容
        taskExecutor.execute(() -> {
            if (contextMap != null) {
                MDC.setContextMap(contextMap); // 将MDC内容设置到新的线程中
            }
            try {
                task.run();
            } finally {
                MDC.clear(); // 清除MDC
            }
        });
    }
}

示例 (使用CompletableFuture):

import org.slf4j.MDC;
import org.springframework.stereotype.Service;

import java.util.Map;
import java.util.concurrent.CompletableFuture;

@Service
public class AsyncService {

    public CompletableFuture<Void> executeAsync(Runnable task) {
        Map<String, String> contextMap = MDC.getCopyOfContextMap();
        return CompletableFuture.runAsync(() -> {
            if (contextMap != null) {
                MDC.setContextMap(contextMap);
            }
            try {
                task.run();
            } finally {
                MDC.clear();
            }
        });
    }
}

5.4 常见问题和解决方案

问题	原因	解决方案
MDC 中的 TraceId 丢失	在异步任务或者线程池中，MDC中的TraceId没有传递到新的线程中。	在启动异步任务前，使用MDC.getCopyOfContextMap()获取当前线程的MDC内容，然后在新的线程中使用MDC.setContextMap()将MDC内容设置到新的线程中。务必在使用完毕后清除MDC，防止内存泄漏。
MDC 内存泄漏	如果没有及时清除MDC，可能会导致内存泄漏。	务必在请求处理完毕后，使用MDC.clear()清除MDC。在使用异步任务时，在finally块中清除MDC，确保即使任务发生异常也能清除MDC。
框架对 MDC 的支持不完善	有些框架对MDC的支持不完善，例如，在使用Spring Cloud Stream时，需要手动配置才能正确传递MDC。	仔细阅读框架的文档，了解其对MDC的支持情况。如果框架没有提供内置的支持，需要手动实现MDC的传递。例如，在使用Spring Cloud Stream时，可以通过自定义MessageConverter来实现MDC的传递。
日志配置错误，看不到 TraceId	日志配置文件没有正确配置以输出MDC中的TraceId。	检查日志配置文件(例如logback.xml, log4j2.xml)，确保配置了输出MDC中TraceId的格式。例如，在logback.xml中使用%X{traceId}来输出TraceId。

6. 最佳实践

• 统一 TraceId Header 名称： 所有服务使用相同的TraceId Header名称，例如X-Trace-Id。
• 尽早设置 TraceId： 在接收到请求后，第一时间从Header中获取TraceId，并将其放入MDC。如果Header中没有TraceId，则生成一个新的TraceId。
• 线程切换时传递 MDC： 在异步任务或者线程池中使用MDC时，需要手动将MDC的内容传递到新的线程中。
• 及时清除 MDC： 在请求处理完毕后，务必清除MDC，防止内存泄漏。
• 使用 AOP 简化 MDC 操作： 可以使用AOP来简化MDC的设置和清除操作，减少代码重复。
• 使用现成的 Trace 系统： 考虑使用现成的Trace系统，例如Zipkin、Jaeger等。这些系统提供了更完善的Trace功能，例如自动传递TraceId、可视化请求链路等。

7. 代码示例：使用 AOP 简化 MDC 操作

import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.slf4j.MDC;
import org.springframework.stereotype.Component;

import java.util.UUID;

@Aspect
@Component
public class TraceIdAspect {

    private static final String TRACE_ID_KEY = "traceId";

    @Around("@annotation(com.example.TraceId)")
    public Object around(ProceedingJoinPoint joinPoint) throws Throwable {
        String traceId = MDC.get(TRACE_ID_KEY);
        if (traceId == null || traceId.isEmpty()) {
            traceId = UUID.randomUUID().toString();
            MDC.put(TRACE_ID_KEY, traceId);
        }
        try {
            return joinPoint.proceed();
        } finally {
            MDC.remove(TRACE_ID_KEY);
        }
    }
}

自定义注解：

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface TraceId {
}

使用示例：

import com.example.TraceId;
import org.springframework.stereotype.Service;

@Service
public class MyService {

    @TraceId
    public void doSomething() {
        // ...
    }
}

只需要在需要TraceId的方法上添加@TraceId注解，就可以自动设置和清除MDC中的TraceId。

8. 使用 Zipkin 或 Jaeger 等分布式追踪系统

虽然手动管理 TraceId 和 MDC 可以实现基本的需求，但是当微服务数量增多，调用链变得更加复杂时，手动管理的难度会大大增加。这时候，使用专业的分布式追踪系统就变得非常必要。

优势:

• 自动传播 TraceId: 大部分追踪系统可以自动完成 TraceId 的传播，无需手动添加 Header 或处理 MDC。
• 可视化调用链: 可以清晰地看到请求经过哪些服务，每个服务的耗时，以及服务之间的依赖关系。
• 性能分析: 可以对请求链路进行性能分析，找出瓶颈所在。
• 错误追踪: 可以快速定位到出错的服务，并查看详细的错误信息。

集成步骤:

1. 引入依赖: 在项目中引入追踪系统的客户端依赖，例如，使用 Spring Cloud Sleuth 集成 Zipkin 或 Jaeger。
2. 配置追踪系统: 配置追踪系统的地址和端口等信息。
3. 启动追踪系统: 启动 Zipkin 或 Jaeger 服务。

Spring Cloud Sleuth 会自动为每个请求生成 TraceId 和 SpanId，并将它们添加到HTTP Header 中。同时，Sleuth 还会自动将 TraceId 放入 MDC 中，方便在日志中使用。

9. 一些经验之谈

• 从一开始就重视 TraceId 的传播： 在项目初期就规划好 TraceId 的传播方案，避免后期重构。
• 保持简单： 尽量选择简单易懂的方案，避免过度设计。
• 监控 TraceId 的传播情况： 定期检查TraceId是否正确传播，及时发现并解决问题。
• 学习和掌握相关的技术： 熟悉MDC、AOP、HTTP Header等技术，才能更好地解决TraceId传播问题。
• 持续学习和实践： 微服务架构和分布式追踪技术不断发展，需要持续学习和实践才能掌握最新的技术。

TraceId 传播是微服务架构的关键

成功地传递TraceId对于构建可观测的微服务系统至关重要。理解传播失败的常见原因，并掌握MDC的正确用法，以及使用现成的分布式追踪系统，可以帮助我们更好地管理和维护复杂的微服务架构，显著提升问题诊断和性能优化的效率。

核心问题总结

1. 遗漏传递和命名不一致是 HTTP Header 传递 TraceId 常见的错误。
2. 线程切换时 MDC 内容丢失和 MDC 内存泄漏是 MDC 使用中的常见问题。
3. 使用 AOP 简化 MDC 操作，并考虑使用现成的 Trace 系统，可以提升效率。