Spring Sleuth追踪头传播自定义教程

理解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 # 定义需要传播的自定义字段

注意事项与最佳实践

1. 服务端处理: 确保SOAP服务的接收端也能够解析这些自定义的SOAP Header。如果服务端也是Spring Boot应用，并且使用了Sleuth，它通常能够自动解析X-B3-*头。对于自定义行李字段，如果需要在服务端继续传播或使用，也可能需要类似的反向处理机制。
2. 命名空间: 在addHeaderElement方法中，为添加的SOAP Header指定一个合适的命名空间是良好的实践，以避免与其他Header冲突。
3. 错误处理: 在handleMessage方法中，添加适当的错误处理和日志记录，以便在出现问题时能够及时发现。
4. 性能影响: Handler链的引入会增加一些处理开销，但对于大多数应用来说，这种开销通常可以忽略不计。
5. 版本兼容性: 确保所使用的Sleuth、JAX-WS和Spring版本相互兼容。brave.Tracer是Sleuth 2.x及更高版本推荐的API。

总结

尽管Spring Sleuth为Rest客户端提供了便捷的分布式追踪头自动传播功能，但对于SOAP调用，特别是在使用jaxws-spring等集成时，需要通过自定义SOAPHandler来实现手动追踪头和行李字段的注入。通过上述步骤，您可以有效地将SOAP服务集成到您的分布式追踪体系中，从而获得完整的端到端可见性，这对于故障排查和性能监控至关重要。这种手动集成的方式，虽然比Rest客户端略显复杂，但提供了高度的灵活性和控制力，确保了即使在异构服务架构中，也能保持一致的追踪能力。