Spring Sleuth在SOAP出站调用中远程字段传播的定制化指南

问题背景与现象

在使用spring sleuth进行分布式追踪时，我们通常会配置sleuth.baggage.remote-fields来传播自定义的业务字段（例如caller-id）。对于基于rest的http客户端（如spring resttemplate、webclient或netflix feign），sleuth提供了开箱即用的支持，这些自定义字段以及标准的b3追踪头部（x-b3-traceid, x-b3-spanid, x-b3-sampled）能够自动注入到出站请求的http头部中，从而实现跨服务的上下文传播。

然而，当应用程序使用SOAP客户端（例如通过jaxws-spring集成JAX-WS）发起出站调用时，会发现尽管REST调用中的自定义字段（如caller-id）能够正确传播，但SOAP请求的头部中却缺少这些字段，导致追踪上下文在SOAP服务调用链中中断。

sleuth:
  async:
    enabled: true
  baggage:
    remote-fields:
      - Caller-Id

REST调用示例（正常工作）：Request headers: {Accept=[application/json; distances], ..., X-B3-TraceId=[...], X-B3-SpanId=[...], X-B3-Sampled=[1], caller-id=[value]}

SOAP调用示例（不工作）：SOAP Headers - {Authorization=[Bearer...]} (缺少Sleuth相关头部和自定义字段)

根本原因分析

Spring Sleuth的自动配置和集成机制主要针对现代Java生态系统中主流的HTTP客户端库。这些库通常提供了统一的拦截器或过滤器机制，Sleuth可以利用这些机制在请求发送前注入追踪上下文信息。

对于SOAP调用，尤其是通过JAX-WS实现的客户端，其底层的HTTP通信机制与REST客户端有所不同。jaxws-spring通常是JAX-WS RI (Reference Implementation) 的Spring集成，而JAX-WS RI底层可能使用HttpURLConnection或其他HTTP客户端库。Sleuth并没有针对所有可能的SOAP客户端或JAX-WS实现提供开箱即用的自动拦截器。因此，SOAP请求在发出时，Sleuth无法自动感知并注入所需的追踪头部和remote-fields。

简而言之，问题在于SOAP客户端所使用的底层HTTP客户端未被Spring Sleuth自动集成，无法自动获取并注入追踪上下文。

Viggle AI

Viggle AI是一个AI驱动的3D动画生成平台，可以帮助用户创建可控角色的3D动画视频。

下载

解决方案：JAX-WS Handler定制化集成

要解决这个问题，我们需要手动将Spring Sleuth的追踪上下文和baggage字段注入到SOAP出站请求中。JAX-WS提供了一种标准的扩展机制——Handler（处理程序），允许我们在消息处理的不同阶段（如请求发送前、响应接收后）拦截和修改SOAP消息。我们可以创建一个自定义的JAX-WS Handler来完成此任务。

1. 核心思路

1. 创建自定义Handler： 实现javax.xml.ws.handler.soap.SOAPHandler接口。
2. 获取Sleuth上下文： 在Handler中，通过Spring容器获取Tracer和BaggageManager实例，从而访问当前的追踪上下文（TraceContext）和所有配置的remote-fields。
3. 注入头部： 在处理出站消息时，从TraceContext中提取B3追踪头部，并从BaggageManager中提取remote-fields的值。将这些值作为HTTP头部或SOAP头部注入到SOAP请求中。

2. 示例代码：SleuthSoapClientHandler

import brave.Span;
import brave.Tracer;
import brave.baggage.BaggageField;
import brave.baggage.BaggageManager;
import brave.propagation.TraceContext;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

import javax.xml.namespace.QName;
import javax.xml.soap.SOAPEnvelope;
import javax.xml.soap.SOAPHeader;
import javax.xml.soap.SOAPMessage;
import javax.xml.ws.handler.MessageContext;
import javax.xml.ws.handler.soap.SOAPHandler;
import javax.xml.ws.handler.soap.SOAPMessageContext;
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;

/**
 * JAX-WS Handler，用于将Spring Sleuth的追踪上下文和baggage字段注入到SOAP出站请求中。
 * 这些字段将作为HTTP请求头附加到SOAP消息的底层HTTP请求中。
 */
public class SleuthSoapClientHandler implements SOAPHandler {

    private final Tracer tracer;
    private final BaggageManager baggageManager;
    private final List remoteFields; // 从Sleuth配置中获取的远程字段名称列表

    // 通过构造函数注入Tracer和BaggageManager，以及配置的remote-fields
    public SleuthSoapClientHandler(Tracer tracer, BaggageManager baggageManager, List remoteFields) {
        this.tracer = tracer;
        this.baggageManager = baggageManager;
        this.remoteFields = remoteFields != null ? remoteFields : Collections.emptyList();
    }

    @Override
    public boolean handleMessage(SOAPMessageContext context) {
        // 判断是否是出站消息
        Boolean outboundProperty = (Boolean) context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);

        if (outboundProperty != null && outboundProperty.booleanValue()) { // 这是一个出站请求
            Span currentSpan = tracer.currentSpan();
            if (currentSpan == null) {
                // 没有活动的Span，无需传播追踪上下文
                return true;
            }

            TraceContext traceContext = currentSpan.context();

            try {
                // 获取HTTP请求头Map，如果不存在则创建
                // MessageContext.HTTP_REQUEST_HEADERS 允许我们操作底层HTTP请求头
                Map> httpHeaders = (Map>) context.get(MessageContext.HTTP_REQUEST_HEADERS);
                if (httpHeaders == null) {
                    httpHeaders = new HashMap<>();
                    context.put(MessageContext.HTTP_REQUEST_HEADERS, httpHeaders);
                    // 设置Scope为APPLICATION，确保这些头在整个请求生命周期中有效
                    context.setScope(MessageContext.HTTP_REQUEST_HEADERS, MessageContext.Scope.APPLICATION);
                }

                // 1. 注入B3追踪头部 (TraceId, SpanId, Sampled)
                // Sleuth通常会通过其自己的传播器将这些头注入到httpHeaders中，但为了确保，我们也可以手动添加
                // 这里我们直接使用TraceContext的信息
                addHttpHeader(httpHeaders, "X-B3-TraceId", traceContext.traceIdString());
                addHttpHeader(httpHeaders, "X-B3-SpanId", traceContext.spanIdString());
                if (traceContext.sampled() != null) {
                    addHttpHeader(httpHeaders, "X-B3-Sampled", traceContext.sampled() ? "1" : "0");
                }

                // 2. 注入remote-fields (baggage) 作为HTTP头部
                for (String fieldName : remoteFields) {
                    BaggageField field = BaggageField.getByName(fieldName);
                    if (field != null) {
                        String value = field.current();
                        if (value != null) {
                            addHttpHeader(httpHeaders, fieldName, value);
                            // 如果目标SOAP服务期望这些字段在SOAP Header中，可以按如下方式添加：
                            // SOAPMessage soapMessage = context.getMessage();
                            // SOAPEnvelope envelope = soapMessage.getSOAPPart().getEnvelope();
                            // SOAPHeader header = envelope.getHeader();
                            // if (header == null) {
                            //     header = envelope.addHeader();
                            // }
                            // QName qName = new QName("http://your.service.namespace.com", fieldName); // 替换为你的SOAP命名空间
                            // header.addHeaderElement(qName).setValue(value);
                        }
                    }
                }

            } catch (Exception e) {
                System.err.println("Error injecting Sleuth headers into SOAP message: " + e.getMessage());
                // 根据需要处理异常，例如记录日志
            }
        }
        return true; // 继续处理消息
    }

    private void addHttpHeader(Map> headers, String name, String value) {
        headers.computeIfAbsent(name, k -> new ArrayList<>()).add(value);
    }

    @Override
    public boolean handleFault(SOAPMessageContext context) {
        // 处理故障消息，这里我们不做特殊处理
        return true;
    }

    @Override
    public void close(MessageContext context) {
        // 资源清理，这里没有需要清理的
    }

    @Override
    public Set getHeaders() {
        // 返回此Handler处理的SOAP Header的QName集合。
        // 由于我们主要操作HTTP Header，这里返回空集合即可。
        return Collections.emptySet();
    }
}

3. 将Handler注册到JAX-WS客户端

创建Handler后，需要将其注册到你的JAX-WS客户端配置中。如果你使用jaxws-spring，这通常在JaxWsPortProxyFactoryBean的配置中完成。

首先，确保Tracer和BaggageManager作为Spring Bean可用（Spring Sleuth会自动提供它们）。然后，你可以像下面这样配置你的SOAP客户端：

import brave.Tracer;
import brave.baggage.BaggageManager;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.remoting.jaxws.JaxWsPortProxyFactoryBean;

import javax.xml.ws.handler.Handler;
import java.net.MalformedURLException;
import java.net.URL;
import java.util.ArrayList;
import java.util.List;

@Configuration
public class SoapClientConfig {

    @Autowired
    private Tracer tracer; // Spring Sleuth提供的Tracer Bean

    @Autowired
    private BaggageManager baggageManager; // Spring Sleuth提供的BaggageManager Bean

    @Value("${sleuth.baggage.remote-fields:}") // 从配置中获取remote-fields
    private List remoteFields;

    @Bean
    public JaxWsPortProxyFactoryBean mySoapServiceClient() throws MalformedURLException {
        JaxWsPortProxyFactoryBean factory = new JaxWsPortProxyFactoryBean();
        factory.setServiceInterface(com.example.MySoapService.class); // 替换为你的SOAP服务接口
        factory.setWsdlDocumentUrl(new URL("classpath:wsdl/MyService.wsdl")); // 替换为你的WSDL路径
        factory.setNamespaceUri("http://example.com/soap"); // 替换为你的SOAP服务命名空间
        factory.setServiceName("MyService"); // 替换为你的SOAP服务名称
        factory.setPortName("MyServicePort"); // 替换为你的SOAP端口名称

        // 创建并注册SleuthSoapClientHandler
        List handlers = new ArrayList<>();
        handlers.add(new SleuthSoapClientHandler(tracer, baggageManager, remoteFields));
        factory.setHandlers(handlers);

        return factory;
    }
}

注意事项：

• remoteFields的获取： 在SleuthSoapClientHandler的构造函数中，我们直接通过@Value注入了sleuth.baggage.remote-fields配置。确保这个列表与你的application.yml或application.properties中的配置一致。
• HTTP Headers vs. SOAP Headers： 示例代码将追踪信息和baggage字段作为HTTP Header注入。这通常是推荐的做法，因为B3追踪规范和baggage字段通常通过HTTP Header传播。如果你的SOAP服务期望这些信息作为SOAP Header的一部分，你需要修改Handler中的代码，使用SOAPMessage对象来添加SOAP Header元素。
• 错误处理： 在实际生产环境中，请添加更健壮的错误处理和日志记录。
• 依赖： 确保项目中包含Spring Sleuth（spring-cloud-starter-sleuth）和JAX-WS相关的依赖（如jaxws-api, jaxws-rt，以及jaxws-spring）。

总结

虽然Spring Sleuth为REST客户端提供了强大的开箱即用追踪能力，但对于SOAP等其他协议，可能需要进行定制化集成。通过利用JAX-WS的Handler机制，我们可以