当前位置:

首页 > 编程开发 > Spring Sleuth追踪头传播自定义教程

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

SpringSleuth默认支持Rest客户端(如RestTemplate、WebClient、Feign)的分布式追踪头自动传播,但对于SOAP调用,如通过jaxws-spring发起的请求,则无法开箱即用地实现。本文将深入探讨Sleuth的集成机制,解释SOAP调用中追踪头传播失效的原因,并提供通过自定义SOAPHandler手动注入追踪上下文和行李字段的详细解决方案,确保SOAP服务也能融入分布式追踪体系。

本文目录

    Spring Sleuth与SOAP:自定义追踪头传播指南

    Spring Sleuth默认支持Rest客户端(如RestTemplate、WebClient、Feign)的分布式追踪头自动传播,但对于SOAP调用,如通过jaxws-spring发起的请求,则无法开箱即用地实现。本文将深入探讨Sleuth的集成机制,解释SOAP调用中追踪头传播失效的原因,并提供通过自定义SOAPHandler手动注入追踪上下文和行李字段的详细解决方案,确保SOAP服务也能融入分布式追踪体系。

    理解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客户端略显复杂,但提供了高度的灵活性和控制力,确保了即使在异构服务架构中,也能保持一致的追踪能力。

    本站声明:本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系bd@zhengruan.com
    作者最新文章
    编程开发
    相关文章 更多
    QQ影音怎么加速播放视频课程
    QQ影音怎么加速播放视频课程

    播放时右键选播放速度,或点控制条倍速,1.25 到 1.5 倍看课最舒服;公式代码类内容别超过 1.25 倍。

    企业微信创建企业提示失败怎么办 实名与填写检查
    企业微信创建企业提示失败怎么办 实名与填写检查

    先看提示属于哪类:名称占用就加后缀,实名不一致就重填本人信息,证件不清晰就重拍。统一社会信用代码逐位核对,连续三次失败别改材料重投,直接联系客服人工核。

    Modern Web Guidance 的 legacy-scan 反转建议应该怎样判断?
    Modern Web Guidance 的 legacy-scan 反转建议应该怎样判断?

    说明源码提交对字符串、生成器和数组的识别边界,以及扫描命令与发行包核验限制。

    Codex 0.170.0 正式版的语音与连接更新,适用范围有哪些限制?
    Codex 0.170.0 正式版的语音与连接更新,适用范围有哪些限制?

    0.170.0 的语音更新限于终端通话协商能力的明确新增,同名工具服务器跨环境支持仍标注实验性质;连接部分则修复大请求回退、认证竞态和云端重连等具体问题。这份正式版公告不足以证明所有账户、所有客户端都已具备完整语音功能。

    Hy4 flash 三种权重怎么选,安装和授权要注意哪些条件?
    Hy4 flash 三种权重怎么选,安装和授权要注意哪些条件?

    了解Hy4 flash、FP8与base的适用任务,阅读官方安装及图文代码,并核对资源和MaaS许可条件。

    OpenAI Python SDK 3.55.0 升级看点:Live MCP 服务配置与预算接口变化
    OpenAI Python SDK 3.55.0 升级看点:Live MCP 服务配置与预算接口变化

    OpenAI Python SDK 3.55.0 升级看点:Live MCP 服务配置与预算接口变化。说明已核实的更新范围、类型兼容性和本地版本确认方法。

    OpenAI Java SDK 4.108.0 的两项新增能力适合哪些项目?
    OpenAI Java SDK 4.108.0 的两项新增能力适合哪些项目?

    OpenAI Java SDK 4.108.0 面向 Live MCP 工具接入与 Managed Agents 预算状态处理,说明新增模型、事件含义、正式发布范围和适用限制。

    Free Claude Code 6.19.37 如何兼顾网页搜索与普通工具调用?
    Free Claude Code 6.19.37 如何兼顾网页搜索与普通工具调用?

    Free Claude Code 6.19.37 在自动搜索时保留客户端工具及选择条件,代理执行搜索后仍返回普通调用。说明适用场景、历史信息保留、请求约束与第三方项目的版本边界。

    Google GenAI Go SDK 1.78.0 的 v1beta 配置优先级怎样判断?
    Google GenAI Go SDK 1.78.0 的 v1beta 配置优先级怎样判断?

    Google GenAI Go SDK 1.78.0 将 Gemini Developer API 默认改为 v1,可用 HTTPOptions.APIVersion 或环境变量保留 v1beta,Vertex AI 默认值不变。

    Google GenAI SDK 3.5.0实时交互值得哪些项目升级评估?
    Google GenAI SDK 3.5.0实时交互值得哪些项目升级评估?

    解释实验性实时支持、环境检查与生产评估中需要验证的条件。

    查看更多
    精品专题 更多
    装机必备
    装机必备

    正软商城装机必备专区,精选办公、浏览器、安全防护、影音播放、压缩解压、设计创作和系统工具等电脑常用正版软件,帮助用户快速完成新电脑软件配置。

    Windows
    Windows

    正软商城Windows软件专区,汇集适用于Windows电脑的办公、设计、安全防护、影音播放、开发工具和系统优化软件,提供软件介绍、系统要求、正版授权及购买下载服务。

    PDF教程
    PDF教程

    正软商城PDF教程频道提供PDF编辑、转换、合并、拆分、压缩及格式处理方法,同时介绍常用PDF软件和工具的使用技巧。

    Mac软件 更多
    讯飞智作 网页版
    讯飞智作 网页版
    Windows/ macOS/ Linux

    讯飞智作是一款基于语音合成技术、虚拟人驱动技术与数字人形象声音构建能力的 AI 数字人音视频创作平台。

    火山引擎 网页版
    火山引擎 网页版
    Windows/ macOS/ Linux

    火山引擎是字节跳动旗下企业级云与AI服务平台。聚焦大模型核心能力,依托字节自研豆包多模态大模型,凭借火山方舟一站式平台,提供模型精调、推理部署、智能应用搭建等全链路服务,结合高性能AI算力,助力各行业快速落地大模型数字化与智能化应用。

    Aperty macOS版
    Aperty macOS版
    macOS

    Aperty 是 Skylum 推出的 AI 人像修图软件,支持自然肤质修饰、瑕疵处理、面部与身体调整、预设及批量同步。

    WINDOWS 更多
    讯飞智作 网页版
    讯飞智作 网页版
    Windows/ macOS/ Linux

    讯飞智作是一款基于语音合成技术、虚拟人驱动技术与数字人形象声音构建能力的 AI 数字人音视频创作平台。

    火山引擎 网页版
    火山引擎 网页版
    Windows/ macOS/ Linux

    火山引擎是字节跳动旗下企业级云与AI服务平台。聚焦大模型核心能力,依托字节自研豆包多模态大模型,凭借火山方舟一站式平台,提供模型精调、推理部署、智能应用搭建等全链路服务,结合高性能AI算力,助力各行业快速落地大模型数字化与智能化应用。

    PixTV 网页版
    PixTV 网页版
    Windows

    PixTV 是一款在浏览器中使用的 AI 视觉内容创作平台,提供图片、视频、音频、文字生成、AI 分镜、局部重绘、提示词反推和无限画布等工具,适合短剧、漫剧、广告及社交媒体内容制作。