Fix Gateway 2.0.x plugin not activated for spring-cloud-starter-gateway 2.0.0.RELEASE

[huangguangshan]

Fix Gateway 2.0.x plugin not activated for spring-cloud-starter-gateway 2.0.0.RELEASE

• Add a unit test to verify that the fix works.
• Explain briefly why the bug exists and how to fix it.

The current implementation of AbstractGateway200EnhancePluginDefineV2 uses
org.springframework.cloud.gateway.config.GatewayAutoConfiguration$1
as a witness class:

@Override
protected String[] witnessClasses() {
    return new String[] { "org.springframework.cloud.gateway.config.GatewayAutoConfiguration$1" };
}

However, in Spring Cloud Gateway 2.0.x, the anonymous inner class $1 does not exist in the bytecode.
This causes the SkyWalking agent to report:
xxx Witness class org.springframework.cloud.gateway.config.GatewayAutoConfiguration$1 does not exist.
and the plugin fails to activate.

Solution

Use a stable, existing class (GatewayAutoConfiguration) as the witness class:

@Override
protected String[] witnessClasses() {
    return new String[] {
        "org.springframework.cloud.gateway.config.GatewayAutoConfiguration"
    };
}


This class exists in all Spring Cloud Gateway 2.0.x versions, so the plugin loads normally.

[wu-sheng]

Please update changes and if some versions were not supported, please update the plugin test versions to verify it is supported with new changes.

[huangguangshan]

Please update changes and if some versions were not supported, please update the plugin test versions to verify it is supported with new changes.

Environment

Spring Cloud Gateway version: 2.0.0.RELEASE

Dependency: spring-cloud-starter-gateway

SkyWalking Java agent version: 9.5.0

Plugin used: apm-spring-cloud-gateway-2.0.x-plugin-9.5.0.jar

Problem Description

When running a Spring Cloud Gateway 2.0.0 application with the SkyWalking Java agent (9.5.0) and enabling the apm-spring-cloud-gateway-2.0.x-plugin, the tracing context becomes inconsistent. The trace ID generated at the gateway does not match the trace ID observed in the downstream application after the request is forwarded.

During application startup, the following error appears in skywalking-api.log:

enhance class org.springframework.web.reactive.DispatcherHandler by plugin
org.apache.skywalking.apm.plugin.spring.cloud.gateway.v20x.define.DispatcherHandlerInstrumentation
is not activated. Witness class org.springframework.cloud.gateway.config.GatewayAutoConfiguration$1 does not exist.

The same error repeats across several plugin enhancement attempts, indicating that multiple instrumentation definitions are being skipped.

Root Cause

The SkyWalking plugin for Spring Cloud Gateway 2.0.x uses the following witness class:

org.springframework.cloud.gateway.config.GatewayAutoConfiguration$1

However, in Spring Cloud Gateway 2.0.0, the anonymous inner class $1 does not exist in the bytecode.
As a result, all instrumentations that rely on this witness class fail to activate, causing the gateway plugin to be skipped entirely.

This explains why instrumentation for key classes—such as DispatcherHandler—is not applied, ultimately leading to trace ID inconsistency.

[wu-sheng]

If this is the case, you should face error run this test scenario,

https://github.com/apache/skywalking-java/blob/main/test/plugin/scenarios/gateway-2.0.x-scenario/support-version.list

We can see it poassed on 2.0.4.
Please check the difference.

[huangguangshan]

If this is the case, you should face error run this test scenario,

https://github.com/apache/skywalking-java/blob/main/test/plugin/scenarios/gateway-2.0.x-scenario/support-version.list

We can see it poassed on 2.0.4. Please check the difference.

The test case uses spring-cloud-starter-gateway 2.0.2.RELEASE, and it works correctly with this version.
However, when using 2.0.0.RELEASE, the plugin is not supported and fails to work.

[wu-sheng]

Please update the changes.md about what you changed.

[huangguangshan]

• Update the [CHANGES.md]

[wu-sheng]

If this is the case, you should face error run this test scenario,
https://github.com/apache/skywalking-java/blob/main/test/plugin/scenarios/gateway-2.0.x-scenario/support-version.list
We can see it poassed on 2.0.4. Please check the difference.

The test case uses spring-cloud-starter-gateway 2.0.2.RELEASE, and it works correctly with this version. However, when using 2.0.0.RELEASE, the plugin is not supported and fails to work.

By that, I mean, all versions in support-version.list will trigger the re-packaging and re-testing. So, if you added 2.0.0.RELEASE to that case, it should fails. And your new codes should pass.
That is how we verify plugins with versions compatibility for the global users.
Please verify that.

[wu-sheng]

The version decleared here will be will be replaced by the list mentioned above. So, 2.0.4 is just one tested version.

[wu-sheng]

I think you should run this(2.0.0) locally, and confirm it would fail. And post local logs here.

[wu-sheng]

You can see the updated case failed.
Please rerun locally, and address the issue.

https://github.com/apache/skywalking-java/actions/runs/19283932635/job/55141865683?pr=779

[huangguangshan]

The version decleared here will be will be replaced by the list mentioned above. So, 2.0.4 is just one tested version.

Hello, when running local tests for gateway-projectA-scenario, an error occurs:
Caused by: java.lang.ClassNotFoundException: reactor.core.scheduler.NonBlocking
This happens when the spring-cloud-starter-gateway version is set to 2.0.0.RELEASE.

Adding a manual dependency on reactor-core:3.1.7.RELEASE in the pom.xml file resolves the issue.

I’d like to confirm whether this solution aligns with your expectations or project standards.

[huangguangshan]

I think you should run this(2.0.0) locally, and confirm it would fail. And post local logs here.

When running locally with Spring Cloud Gateway 2.0.0, the skywalking-api.log shows the following warnings:

WARN 2025-11-12 15:01:27.054 main AbstractClassEnhancePluginDefine : enhance class reactor.ipc.netty.http.client.HttpClient by plugin org.apache.skywalking.apm.plugin.spring.cloud.gateway.v20x.define.HttpClientInstrumentation is not activated. Witness class org.springframework.cloud.gateway.config.GatewayAutoConfiguration$1 does not exist.
WARN 2025-11-12 15:01:27.128 main AbstractClassEnhancePluginDefine : enhance class org.springframework.cloud.gateway.filter.NettyRoutingFilter by plugin org.apache.skywalking.apm.plugin.spring.cloud.gateway.v20x.define.NettyRoutingFilterInstrumentation is not activated. Witness class org.springframework.cloud.gateway.config.GatewayAutoConfiguration$1 does not exist.
WARN 2025-11-12 15:01:27.691 main AbstractClassEnhancePluginDefine : enhance class org.springframework.cloud.gateway.handler.FilteringWebHandler$GatewayFilterAdapter by plugin org.apache.skywalking.apm.plugin.spring.cloud.gateway.v20x.define.GatewayFilterInstrumentation is not activated. Witness class org.springframework.cloud.gateway.config.GatewayAutoConfiguration$1 does not exist.
WARN 2025-11-12 15:01:27.692 main AbstractClassEnhancePluginDefine : enhance class org.springframework.cloud.gateway.filter.OrderedGatewayFilter by plugin org.apache.skywalking.apm.plugin.spring.cloud.gateway.v20x.define.GatewayFilterInstrumentation is not activated. Witness class org.springframework.cloud.gateway.config.GatewayAutoConfiguration$1 does not exist.

[wu-sheng]

The version decleared here will be will be replaced by the list mentioned above. So, 2.0.4 is just one tested version.

Hello, when running local tests for gateway-projectA-scenario, an error occurs:

Caused by: java.lang.ClassNotFoundException: reactor.core.scheduler.NonBlocking

This happens when the spring-cloud-starter-gateway version is set to 2.0.0.RELEASE.

Adding a manual dependency on reactor-core:3.1.7.RELEASE in the pom.xml file resolves the issue.

I’d like to confirm whether this solution aligns with your expectations or project standards.

You could try to add that to projectA(2.0.x), if it doesn't affect 2.0.4, then we are good.
After all, that is for testing only.

[huangguangshan]

The version decleared here will be will be replaced by the list mentioned above. So, 2.0.4 is just one tested version.

Hello, when running local tests for gateway-projectA-scenario, an error occurs:
Caused by: java.lang.ClassNotFoundException: reactor.core.scheduler.NonBlocking
This happens when the spring-cloud-starter-gateway version is set to 2.0.0.RELEASE.
Adding a manual dependency on reactor-core:3.1.7.RELEASE in the pom.xml file resolves the issue.
I’d like to confirm whether this solution aligns with your expectations or project standards.

You could try to add that to projectA(2.0.x), if it doesn't affect 2.0.4, then we are good. After all, that is for testing only.

I’ve submitted the modification, and the test case gateway-2.0.x-scenario is now running normally.
There’s one failed test case under CI / Java 17 / macOS, but I believe it’s unrelated to my changes — is that okay?