理解Spring Sleuth的追踪机制
spring sleuth是spring cloud生态系统中的一个组件，旨在为分布式系统提供链路追踪能力。它通过在服务间传递追踪id（trace id）和跨度id（span id）来关联请求，从而帮助开发者理解请求流、诊断性能问题和定位错误。sleuth的开箱即用功能主要依赖于对常见http客户端库的自动配置和增强，例如：
- RestTemplate: Spring框架提供的同步HTTP客户端。
- WebClient: Spring WebFlux提供的响应式HTTP客户端。
- Feign: Netflix开发的声明式HTTP客户端，常用于微服务间的REST调用。
当应用程序使用这些客户端发起HTTP请求时，Sleuth会自动拦截请求，从当前追踪上下文中提取Trace ID、Span ID、采样状态（Sampled）以及配置的自定义行李字段（Baggage fields，如Caller-Id），并将它们作为HTTP请求头（通常是X-B3-TraceId, X-B3-SpanId, X-B3-Sampled等）注入到传出的请求中。接收方服务如果也集成了Sleuth，则会自动解析这些头部，并继续追踪链。
SOAP服务追踪的挑战与限制
尽管Sleuth对RESTful服务（特别是通过Feign、RestTemplate等发起的）提供了无缝的追踪能力，但对于SOAP服务，情况则有所不同。问题在于SOAP服务通常不直接使用上述Sleuth自动支持的HTTP客户端。例如，当使用jaxws-spring这样的库来集成JAX-WS（Java API for XML Web Services）时，底层用于发起SOAP调用的HTTP客户端可能不是Sleuth默认集成的那些。JAX-WS的实现（如Apache CXF、Metro）会使用自己的底层HTTP传输机制，例如Java内置的HttpURLConnection或配置的Apache HttpClient等。
由于Sleuth无法识别并自动增强这些特定的SOAP底层HTTP客户端，因此它无法将追踪上下文（包括X-B3-*头部和自定义行李字段）自动注入到SOAP请求的HTTP头部中。这就是为什么在REST调用中Caller-Id等字段能够成功传播，而在SOAP调用中却缺失的原因。
手动集成Sleuth与JAX-WS/SOAP服务
为了解决SOAP服务追踪的问题，我们需要进行手动集成。这通常涉及在JAX-WS客户端的请求处理链中插入自定义的拦截器（或称为处理器/Handler），在该拦截器中手动获取当前的Sleuth追踪上下文，并将其注入到SOAP请求的HTTP头部中。
1. 引入必要的依赖
确保项目中包含Spring Sleuth和JAX-WS相关的依赖。
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-sleuth</artifactId>
</dependency>
<dependency>
<groupId>com.revinate</groupId>
<artifactId>jaxws-spring</artifactId>
<version>1.0.0</version>
</dependency>
<!-- 如果底层使用CXF，可能还需要CXF相关依赖 -->
<dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-frontend-jaxws</artifactId>
<version>${cxf.version}</version>
</dependency>
<dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-transports-http</artifactId>
<version>${cxf.version}</version>
</dependency>2. 创建JAX-WS客户端处理器（Handler）
我们需要实现javax.xml.ws.handler.soap.SOAPHandler接口，在handleMessage方法中处理出站消息。
import brave.Span;
import brave.Tracer;
import brave.propagation.Propagation;
import brave.propagation.TraceContext;
import brave.propagation.TraceContext.Injector;
import brave.propagation.TraceContext.Extractor;
import brave.http.HttpTracing;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
import javax.xml.namespace.QName;
import javax.xml.ws.handler.MessageContext;
import javax.xml.ws.handler.soap.SOAPHandler;
import javax.xml.ws.handler.soap.SOAPMessageContext;
import java.util.Collections;
import java.util.HashSet;
import java.util.Map;
import java.util.Set;
import java.util.HashMap;
@Component
public class SleuthSoapClientHandler implements SOAPHandler<SOAPMessageContext> {
private final Tracer tracer;
private final Propagation.Setter<Map<String, String>, String> headerSetter;
private final Propagation.Getter<Map<String, String>, String> headerGetter; // 尽管是出站，但为了完整性可以考虑
// 构造函数注入Tracer和HeaderSetter
@Autowired
public SleuthSoapClientHandler(Tracer tracer, HttpTracing httpTracing) {
this.tracer = tracer;
// 使用B3TextMapPropagation的Setter来注入B3头部
// 对于自定义行李字段，需要单独处理或使用BaggagePropagation
this.headerSetter = httpTracing.propagation().injector(Map::put);
this.headerGetter = httpTracing.propagation().extractor(Map::get); // 示例，通常出站不需要getter
}
@Override
public boolean handleMessage(SOAPMessageContext context) {
Boolean outboundProperty = (Boolean) context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);
if (outboundProperty) { // 仅处理出站消息
Span currentSpan = tracer.currentSpan();
if (currentSpan == null) {
// 如果没有当前Span，则可能是一个新的调用链的开始，或者不在Sleuth追踪的线程中
// 此时可以选择创建一个新的Span，或者不注入任何头部
// 为了与现有追踪链保持一致，我们通常只在有当前Span时注入
return true;
}
// 获取当前HTTP请求头部
Map<String, Object> requestHeaders = (Map<String, Object>) context.get(MessageContext.HTTP_REQUEST_HEADERS);
if (requestHeaders == null) {
requestHeaders = new HashMap<>();
context.put(MessageContext.HTTP_REQUEST_HEADERS, requestHeaders);
}
// 将Sleuth追踪上下文注入到HTTP头部中
Map<String, String> stringHeaders = new HashMap<>();
headerSetter.inject(currentSpan.context(), stringHeaders);
// 将stringHeaders转换并添加到实际的requestHeaders中
stringHeaders.forEach((key, value) -> {
// JAX-WS的HTTP_REQUEST_HEADERS通常期望List<String>作为值
requestHeaders.put(key, Collections.singletonList(value));
});
// 额外处理自定义行李字段（如Caller-Id）
// Sleuth的Baggage API提供了获取和设置行李字段的方法
String callerId = tracer.currentSpan().context().findBaggage("Caller-Id");
if (callerId != null && !callerId.isEmpty()) {
requestHeaders.put("Caller-Id", Collections.singletonList(callerId));
}
// 更新消息上下文中的HTTP请求头部
context.put(MessageContext.HTTP_REQUEST_HEADERS, requestHeaders);
context.setScope(MessageContext.HTTP_REQUEST_HEADERS, MessageContext.Scope.APPLICATION);
}
return true;
}
@Override
public boolean handleFault(SOAPMessageContext context) {
return true;
}
@Override
public void close(MessageContext context) {
// 清理资源，如果需要
}
@Override
public Set<QName> getHeaders() {
// 返回此处理器感兴趣的SOAP Header，通常为空，因为我们处理的是HTTP Header
return new HashSet<>();
}
}注意事项：
- headerSetter.inject(currentSpan.context(), stringHeaders); 会将Sleuth默认的追踪头部（如X-B3-TraceId, X-B3-SpanId, X-B3-Sampled等）注入到stringHeaders中。
- 对于自定义行李字段（如Caller-Id），需要通过tracer.currentSpan().context().findBaggage("Caller-Id")显式获取，然后手动添加到HTTP头部。
- MessageContext.HTTP_REQUEST_HEADERS通常期望Map<String, List<String>>作为头部集合。在上述示例中，为了简化，我们将其转换为Map<String, Object>并使用Collections.singletonList(value)来封装单个值。如果需要处理多值头部，则需要更复杂的转换。
3. 配置JAX-WS客户端以使用处理器
有两种常见的方式来配置JAX-WS客户端使用这个自定义处理器：
a) 通过Spring配置（如果使用jaxws-spring）
在你的Spring配置中，为SOAP客户端代理工厂添加处理器链。
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import javax.xml.ws.BindingProvider;
import javax.xml.ws.handler.Handler;
import java.util.ArrayList;
import java.util.List;
@Configuration
public class SoapClientConfig {
@Autowired
private SleuthSoapClientHandler sleuthSoapClientHandler;
@Bean
public MySoapService mySoapService() {
// 假设MySoapService是你的SOAP服务接口
// 这是获取SOAP服务代理的一个示例，具体方式取决于你的jaxws-spring配置
// 可能是通过FactoryBean或者直接的JaxWsPortProxyFactoryBean
MySoapService service = new MySoapServiceService().getMySoapServicePort();
if (service instanceof BindingProvider) {
BindingProvider bp = (BindingProvider) service;
List<Handler> handlerChain = new ArrayList<>();
handlerChain.add(sleuthSoapClientHandler);
bp.getBinding().setHandlerChain(handlerChain);
}
return service;
}
// 如果你使用JaxWsPortProxyFactoryBean，配置会更直接
// @Bean
// public JaxWsPortProxyFactoryBean mySoapServiceProxy() {
// JaxWsPortProxyFactoryBean factory = new JaxWsPortProxyFactoryBean();
// factory.setServiceName("MySoapServiceService");
// factory.setPortName("MySoapServicePort");
// factory.setServiceInterface(MySoapService.class);
// factory.setWsdlDocumentUrl("classpath:wsdl/MySoapService.wsdl");
// // 设置处理器链
// factory.setHandlerChain(Collections.singletonList(sleuthSoapClientHandler));
// return factory;
// }
}b) 通过代码直接设置（如果手动创建客户端）
import javax.xml.ws.BindingProvider;
import javax.xml.ws.handler.Handler;
import java.util.ArrayList;
import java.util.List;
// ...
public class MyClient {
@Autowired
private SleuthSoapClientHandler sleuthSoapClientHandler;
public void callSoapService() {
MySoapServiceService serviceLocator = new MySoapServiceService();
MySoapService mySoapService = serviceLocator.getMySoapServicePort();
if (mySoapService instanceof BindingProvider) {
BindingProvider bp = (BindingProvider) mySoapService;
List<Handler> handlerChain = new ArrayList<>();
handlerChain.add(sleuthSoapClientHandler);
bp.getBinding().setHandlerChain(handlerChain);
}
// 现在可以调用SOAP服务了
// mySoapService.someOperation();
}
}总结
Spring Sleuth为分布式系统提供了强大的链路追踪能力，但其开箱即用的自动传播功能主要针对RestTemplate、WebClient和Feign等主流HTTP客户端。对于SOAP服务，由于其底层HTTP客户端实现机制的差异，Sleuth无法直接进行集成。
要实现SOAP服务的分布式追踪，开发者需要通过JAX-WS提供的客户端处理器（Handler）机制进行手动集成。核心步骤是创建一个自定义的SOAP处理器，在其中获取当前的Sleuth追踪上下文（包括Trace ID、Span ID和自定义行李字段），并将其作为HTTP头部手动注入到出站的SOAP请求中。通过这种方式，即使是SOAP服务调用，也能无缝地融入到整个分布式追踪链中，从而保持完整的可观测性。
