SkyWalking 对 Spring Cloud Gateway 中 GlobalFilter 和 GatewayFilter 的追踪支持

在分布式系统架构中，Spring Cloud Gateway 作为微服务架构的API网关，承担着重要的请求路由和过滤功能。其中，GlobalFilter 和 GatewayFilter 是网关处理请求的核心组件。然而，在实际应用中，开发者经常遇到在这些过滤器中无法正确获取和传递 traceId 的问题，这给分布式追踪带来了挑战。

问题背景

在 Spring Cloud Gateway 中，自定义的 GlobalFilter 实现类通常无法直接获取 SkyWalking 的 traceId。例如，在以下代码中：

@Component
public class Filter1 implements GlobalFilter, Ordered {
    private static Logger log = LoggerFactory.getLogger(Filter1.class);

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        // 这里无法获取traceId
        log.info("filter1 traceId: {}", TraceContext.traceId());
        return chain.filter(exchange);
    }

    @Override
    public int getOrder() {
        return -100;
    }
}

开发者期望能够在自定义的 GlobalFilter 中获取 SkyWalking 的 traceId，但实际上 TraceContext.traceId() 返回的是空值。这种情况会导致分布式追踪链路的中断，使得网关层的过滤操作无法被正确记录和关联。

技术解决方案

为了解决这个问题，我们需要对 Spring Cloud Gateway 的插件进行扩展，使其能够支持对 GatewayFilter 的追踪。核心思路是通过字节码增强技术，在 GatewayFilter 的 filter 方法执行前后插入追踪逻辑。

实现要点

1. 类匹配机制：通过 HierarchyMatch 匹配所有实现了 GatewayFilter 接口的类。

2. 方法拦截点：针对 filter 方法进行拦截，特别是那些接收 ServerWebExchange 作为第一个参数的方法。

3. 上下文传递：在拦截器中处理上下文的创建和传递，确保 traceId 的正确传播。

核心代码实现

插桩定义

public class GatewayFilterInstrumentation extends AbstractGateway210EnhancePluginDefine {
    @Override
    protected ClassMatch enhanceClass() {
        return HierarchyMatch.byHierarchyMatch("org.springframework.cloud.gateway.filter.GatewayFilter");
    }

    @Override
    public InstanceMethodsInterceptPoint[] getInstanceMethodsInterceptPoints() {
        return new InstanceMethodsInterceptPoint[] {
            new InstanceMethodsInterceptPoint() {
                @Override
                public ElementMatcher<MethodDescription> getMethodsMatcher() {
                    return named("filter").and(
                        takesArgumentWithType(0, "org.springframework.web.server.ServerWebExchange"));
                }

                @Override
                public String getMethodsInterceptor() {
                    return "org.apache.skywalking.apm.plugin.spring.cloud.gateway.v21x.GatewayFilterInterceptor";
                }

                @Override
                public boolean isOverrideArgs() {
                    return true;
                }
            }
        };
    }
}

拦截器实现

public class GatewayFilterInterceptor implements InstanceMethodsAroundInterceptor {
    private int stackDeep = 0;

    @Override
    public void beforeMethod(EnhancedInstance objInst, Method method, Object[] allArguments, 
                           Class<?>[] argumentsTypes, MethodInterceptResult result) {
        stackDeep++;
        if (isEntry()) {
            ServerWebExchange exchange = (ServerWebExchange) allArguments[0];
            EnhancedInstance enhancedInstance = getInstance(exchange);

            AbstractSpan span = ContextManager.createLocalSpan("SpringCloudGateway/GatewayFilter");
            if (enhancedInstance != null && enhancedInstance.getSkyWalkingDynamicField() != null) {
                ContextManager.continued((ContextSnapshot) enhancedInstance.getSkyWalkingDynamicField());
            }
            span.setComponent(SPRING_CLOUD_GATEWAY);
        }
    }

    // ... 其他方法实现
}

实现原理

该解决方案的核心在于：

1. 调用栈深度管理：通过 stackDeep 变量跟踪方法调用深度，确保只在最外层调用时创建新的Span。

2. 上下文传递：从 ServerWebExchange 中获取可能存在的上下文快照(ContextSnapshot)，并通过 ContextManager.continued() 方法恢复上下文。

3. Span生命周期管理：在适当的时机创建和关闭Span，确保追踪数据的完整性。

4. 异常处理：在方法抛出异常时，将异常信息记录到当前活跃的Span中。

实际应用价值

这个增强功能为开发者带来了以下好处：

1. 完整的追踪链路：现在可以在网关的各个过滤器中获取正确的traceId，确保分布式追踪链路的完整性。

2. 更细粒度的监控：能够监控每个过滤器的执行情况和性能指标。

3. 问题诊断便利：当网关出现问题时，可以快速定位是哪个过滤器导致了问题。

4. 上下文一致性：确保了在整个请求处理过程中，上下文信息的正确传递和一致性。

总结

通过对 Spring Cloud Gateway 插件的这一增强，SkyWalking 提供了对网关过滤器的全面追踪支持。这不仅解决了开发者在实际应用中遇到的traceId获取问题，还提升了整个分布式系统的可观测性。这种基于字节码增强的解决方案既保持了代码的非侵入性，又提供了强大的追踪能力，是分布式追踪领域的一个典型实践。