理解Spring Sleuth的自动集成机制
spring cloud sleuth是spring生态中实现分布式追踪的关键组件，它通过集成opentracing或opentelemetry标准，为服务间的调用自动注入追踪上下文（trace id、span id等）。sleuth的开箱即用功能主要集中在常见的http客户端上，这些客户端通常通过拦截器或aop的方式被sleuth增强，从而在请求头中自动添加如x-b3-traceid、x-b3-spanid、x-b3-sampled等b3追踪头，以及通过sleuth.baggage.remote-fields配置的自定义行李字段（如caller-id）。
当使用Feign等Rest客户端发起HTTP请求时，Sleuth能够无缝地捕获当前线程的追踪上下文，并将其注入到HTTP请求头中，如下所示：
Request headers: {..., X-B3-TraceId=[...], X-B3-SpanId=[...], X-B3-Sampled=[1], caller-id=[value]}这确保了Rest服务之间的调用链可以被完整地追踪。
SOAP调用中的追踪头传播挑战
然而，对于SOAP调用，特别是通过JAX-WS或其Spring集成（如jaxws-spring）发起的请求，Sleuth的自动集成机制通常无法生效。这是因为SOAP客户端通常不属于Sleuth默认集成的HTTP客户端范畴。JAX-WS客户端在底层可能使用不同的HTTP传输层实现，或者其消息处理机制与Sleuth预期的拦截点不符。因此，即使配置了sleuth.baggage.remote-fields，SOAP请求的头部也可能只包含应用程序或容器默认添加的少数几个头，而缺少Sleuth所需的追踪信息：
SOAP Headers - {Authorization=[Bearer...]} // 缺少追踪头和自定义行李字段这意味着SOAP服务之间的调用链会中断，无法实现完整的端到端分布式追踪。
解决方案：通过SOAPHandler实现手动传播
为了在SOAP调用中实现分布式追踪头的传播，我们需要利用JAX-WS提供的扩展点——SOAPHandler机制。通过自定义一个SOAPHandler，我们可以在SOAP请求发送前，手动获取当前的Sleuth追踪上下文，并将其中的Trace ID、Span ID、采样状态以及自定义行李字段注入到SOAP请求的SOAP Header中。
1. 核心原理
- 获取追踪上下文: 使用Spring Cloud Sleuth提供的Tracer bean来获取当前线程的Span信息。
- 构造SOAP头部: 将从Span中提取的Trace ID、Span ID、采样状态，以及从BaggageManager中获取的自定义行李字段，作为SOAPHeaderElement添加到SOAP消息的Header部分。
- 注册Handler: 将自定义的SOAPHandler注册到JAX-WS客户端的Handler链中。
2. 示例代码：自定义TracingSOAPClientHandler
首先，创建一个实现SOAPHandler
import brave.Tracer; import brave.Span; import brave.propagation.BaggageField; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Component; import javax.xml.namespace.QName; import javax.xml.soap.*; 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.Set; @Component public class TracingSOAPClientHandler implements SOAPHandler{ // Spring Boot 2.x 推荐使用 brave.Tracer @Autowired private Tracer tracer; // 自定义行李字段，需要与sleuth.baggage.remote-fields配置一致 private static final BaggageField CALLER_ID = BaggageField.create("Caller-Id"); @Override public Set getHeaders() { // 返回此Handler感兴趣的SOAP Header QName集合。 // 在本例中，我们是添加Header，所以可以返回空集或我们即将添加的Header QName。 // 为了简单起见，这里返回空集。 return Collections.emptySet(); } @Override public boolean handleMessage(SOAPMessageContext context) { Boolean outboundProperty = (Boolean) context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY); // 只处理出站消息（客户端发送请求） if (outboundProperty) { Span currentSpan = tracer.currentSpan(); if (currentSpan != null) { try { SOAPMessage soapMessage = context.getMessage(); SOAPEnvelope soapEnvelope = soapMessage.getSOAPPart().getEnvelope(); SOAPHeader soapHeader = soapEnvelope.getHeader(); // 如果没有Header，则创建一个 if (soapHeader == null) { soapHeader = soapEnvelope.addHeader(); } // 添加B3追踪头 addHeaderElement(soapHeader, "X-B3-TraceId", currentSpan.context().traceIdString()); addHeaderElement(soapHeader, "X-B3-SpanId", currentSpan.context().spanIdString()); if (currentSpan.context().sampled() != null) { addHeaderElement(soapHeader, "X-B3-Sampled", currentSpan.context().sampled() ? "1" : "0"); } // 添加自定义行李字段 String callerId = CALLER_ID.get(); if (callerId != null) { addHeaderElement(soapHeader, "Caller-Id", callerId); } soapMessage.saveChanges(); // 保存对SOAP消息的修改 } catch (SOAPException e) { System.err.println("Error adding tracing headers to SOAP message: " + e.getMessage()); // 实际应用中应使用日志框架 } } } return true; // 继续处理消息 } private void addHeaderElement(SOAPHeader soapHeader, String name, String value) throws SOAPException { // 建议使用一个命名空间，例如 "http://spring.io/sleuth/tracing" QName qName = new QName("http://spring.io/sleuth/tracing", name); SOAPHeaderElement headerElement = soapHeader.addHeaderElement(qName); headerElement.setValue(value); } @Override public boolean handleFault(SOAPMessageContext context) { return true; // 继续处理故障 } @Override public void close(MessageContext context) { // 资源清理（如果需要） } }
3. 注册TracingSOAPClientHandler
将上述TracingSOAPClientHandler注册到JAX-WS客户端有两种常见方式：
方法一：通过Spring配置（推荐，如果使用jaxws-spring）
如果您的JAX-WS客户端是通过jaxws-spring配置的，通常会有类似JaxWsPortProxyFactoryBean或JaxWsDynamicClientFactory的配置。您可以在这里注入Handler：
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.remoting.jaxws.JaxWsPortProxyFactoryBean;
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 TracingSOAPClientHandler tracingSOAPClientHandler;
@Bean
public YourSoapService yourSoapService() {
JaxWsPortProxyFactoryBean factory = new new JaxWsPortProxyFactoryBean();
factory.setServiceName("YourSoapService");
factory.setWsdlDocumentUrl("classpath:wsdl/yourService.wsdl");
factory.setNamespaceUri("http://your.service.namespace/");
factory.setPortName("YourSoapServicePort");
factory.setServiceInterface(YourSoapService.class);
// 设置自定义Handler
List handlers = new ArrayList<>();
handlers.add(tracingSOAPClientHandler);
factory.setHandlers(handlers);
factory.afterPropertiesSet(); // 初始化Bean
return (YourSoapService) factory.getObject();
}
} 方法二：直接在JAX-WS客户端实例上设置
如果您的JAX-WS客户端不是通过jaxws-spring完全管理，或者您需要更细粒度的控制，可以在创建客户端代理后手动添加Handler：
import javax.xml.ws.Service;
import javax.xml.ws.BindingProvider;
import javax.xml.ws.handler.Handler;
import java.net.URL;
import java.util.ArrayList;
import java.util.List;
// 假设 YourSoapService 是通过 wsimport 生成的接口
public class YourSoapClient {
private final YourSoapService yourSoapService;
private final TracingSOAPClientHandler tracingSOAPClientHandler;
public YourSoapClient(TracingSOAPClientHandler tracingSOAPClientHandler) throws Exception {
this.tracingSOAPClientHandler = tracingSOAPClientHandler;
URL wsdlUrl = new URL("http://localhost:8080/services/YourSoapService?wsdl");
QName serviceName = new QName("http://your.service.namespace/", "YourSoapService");
Service service = Service.create(wsdlUrl, serviceName);
this.yourSoapService = service.getPort(YourSoapService.class);
// 获取BindingProvider并设置Handler链
BindingProvider bp = (BindingProvider) this.yourSoapService;
List handlerChain = new ArrayList<>();
handlerChain.add(this.tracingSOAPClientHandler);
bp.getBinding().setHandlerChain(handlerChain);
}
public void callServiceMethod() {
// 调用SOAP服务方法
yourSoapService.someMethod();
}
} 4. Sleuth配置示例
确保您的application.yml或application.properties中包含了Sleuth的相关配置，特别是自定义行李字段：
spring:
sleuth:
async:
enabled: true # 启用异步操作的追踪
baggage:
remote-fields:
- Caller-Id # 定义需要传播的自定义字段注意事项与最佳实践
- 服务端处理: 确保SOAP服务的接收端也能够解析这些自定义的SOAP Header。如果服务端也是Spring Boot应用，并且使用了Sleuth，它通常能够自动解析X-B3-*头。对于自定义行李字段，如果需要在服务端继续传播或使用，也可能需要类似的反向处理机制。
- 命名空间: 在addHeaderElement方法中，为添加的SOAP Header指定一个合适的命名空间是良好的实践，以避免与其他Header冲突。
- 错误处理: 在handleMessage方法中，添加适当的错误处理和日志记录，以便在出现问题时能够及时发现。
- 性能影响: Handler链的引入会增加一些处理开销，但对于大多数应用来说，这种开销通常可以忽略不计。
- 版本兼容性: 确保所使用的Sleuth、JAX-WS和Spring版本相互兼容。brave.Tracer是Sleuth 2.x及更高版本推荐的API。
总结
尽管Spring Sleuth为Rest客户端提供了便捷的分布式追踪头自动传播功能，但对于SOAP调用，特别是在使用jaxws-spring等集成时，需要通过自定义SOAPHandler来实现手动追踪头和行李字段的注入。通过上述步骤，您可以有效地将SOAP服务集成到您的分布式追踪体系中，从而获得完整的端到端可见性，这对于故障排查和性能监控至关重要。这种手动集成的方式，虽然比Rest客户端略显复杂，但提供了高度的灵活性和控制力，确保了即使在异构服务架构中，也能保持一致的追踪能力。
