Expose config to set up the re-transform support explicitly

CHANGES.md

@@ -5,6 +5,9 @@ Release Notes.
 9.1.0
 ------------------
 
+* **IMPORTANT** Expose `SW_ENABLE_RETRANSFORM_SUPPORT` config to set up the re-transform support explicitly, 
+  and close it by default to keep startup delay low. 
+  This was added and enabled in 9.0.0, and we confirmed it would slow down the service launch.
 * Fix hbase onConstruct NPE in the file configuration scenario
 * Fix the issue of createSpan failure caused by invalid request URL in HttpClient 4.x/5.x plugin
 * Optimize ElasticSearch 6.x 7.x plugin compatibility

apm-sniffer/apm-agent-core/src/main/java/org/apache/skywalking/apm/agent/core/conf/Config.java

@@ -174,6 +174,17 @@ public static class Agent {
          * Enable the agent kernel services and instrumentation.
          */
         public static boolean ENABLE = true;
+
+        /**
+         * Enables the Java agent kernel to run in a mode that supports class re-transformation by other agents.
+         * It's recommended to use this mode only if the service has more than one SkyWalking agent installed.
+         *
+         * Be aware that this mode can slow down class loading. As a result, you might experience a higher
+         * startup delay (the time it takes for the program to launch and be ready for use).
+         *
+         * @since 9.1.0
+         */
+        public static boolean ENABLE_RETRANSFORM_SUPPORT = false;
     }
 
     public static class OsInfo {

apm-sniffer/apm-agent/src/main/java/org/apache/skywalking/apm/agent/SkyWalkingAgent.java

@@ -157,8 +157,10 @@ private static AgentBuilder newAgentBuilder() {
                 .with(new SWImplementationContextFactory(NAME_TRAIT));
 
         SWNativeMethodStrategy nativeMethodStrategy = new SWNativeMethodStrategy(NAME_TRAIT);
-        return new SWAgentBuilderDefault(byteBuddy, nativeMethodStrategy)
-                .with(AgentBuilder.DescriptionStrategy.Default.POOL_FIRST);
+        final SWAgentBuilderDefault swAgentBuilder = new SWAgentBuilderDefault(byteBuddy, nativeMethodStrategy);
+        return Config.Agent.ENABLE_RETRANSFORM_SUPPORT ?
+            swAgentBuilder.with(AgentBuilder.DescriptionStrategy.Default.POOL_FIRST)
+            : swAgentBuilder;
     }
 
     private static class Transformer implements AgentBuilder.Transformer {

apm-sniffer/config/agent.config

@@ -83,6 +83,13 @@ agent.ssl_cert_chain_path=${SW_AGENT_SSL_CERT_CHAIN_PATH:}
 # Enable the agent kernel services and instrumentation.
 agent.enable=${SW_AGENT_ENABLE:true}
 
+# Enables the Java agent kernel to run in a mode that supports class re-transformation by other agents.
+# It's recommended to use this mode only if the service has more than one SkyWalking agent installed.
+#
+# Be aware that this mode can slow down class loading. As a result, you might experience a higher
+# startup delay (the time it takes for the program to launch and be ready for use).
+agent.enable_retransform_support={SW_ENABLE_RETRANSFORM_SUPPORT:false}
+
 # Limit the length of the ipv4 list size.
 osinfo.ipv4_list_size=${SW_AGENT_OSINFO_IPV4_LIST_SIZE:10}
 

docs/en/setup/service-agent/java-agent/advanced-features.md

@@ -3,6 +3,7 @@
 * Set the settings through system properties for config file override. Read [setting override](Setting-override.md).
 * Use gRPC TLS to link backend. See [open TLS](TLS.md)
 * Set client [token](Token-auth.md) if backend open the token authentication.
+* Activate [re-transform support](re-transform.md) when you need more than one agent.
 * Application Toolkit, are a collection of libraries, provided by SkyWalking APM. Using them, you have a bridge between your application and SkyWalking APM agent.
     * If you want your codes to interact with SkyWalking agent, including `getting trace id`, `setting tags`, `propagating custom data` etc.. Try [SkyWalking manual APIs](Application-toolkit-trace.md).
     * If you require customized metrics, try [SkyWalking Meter System Toolkit](Application-toolkit-meter.md).

docs/en/setup/service-agent/java-agent/re-transform.md

@@ -0,0 +1,35 @@
+# Re-transform Support
+
+By default, the SkyWalking agent is not expected to install alongside other Java agents.
+Therefore, in cases where class re-transformation occurs, the instrumentation provided by 
+SkyWalking could potentially be overwritten or lost.
+
+The limitation of the default type description strategy, **HYBRID**, is described as following.
+> A description type strategy represents a type as a TypeDescription.ForLoadedType if a 
+retransformation or redefinition is applied on a type. Using a loaded type typically results in better performance 
+as no I/O is required for resolving type descriptions. However, any interaction with the type is carried out via the Java reflection API. 
+Using the reflection API triggers eager loading of any type that is part of a method or field signature. 
+If any of these types are missing from the class path, this eager loading will cause a NoClassDefFoundError. 
+Some Java code declares optional dependencies to other classes which are only realized if the optional dependency is present. 
+Such code relies on the Java reflection API not being used for types using optional dependencies.
+
+In certain scenarios, users may need to have multiple agents installed.
+To accommodate this, they should enable this new feature by setting this configuration to true.
+
+```
+# Enables the Java agent kernel to run in a mode that supports class re-transformation by other agents.
+# It's recommended to use this mode only if the service has more than one SkyWalking agent installed.
+#
+# Be aware that this mode can slow down class loading. As a result, you might experience a higher
+# startup delay (the time it takes for the program to launch and be ready for use).
+agent.enable_retransform_support={SW_ENABLE_RETRANSFORM_SUPPORT:false}
+```
+
+This option would change the type description strategy to `POOL_FIRST`.
+But, **doing so can cause overhead as processing loaded types is supported very efficiently by a JVM.**
+and slow down class loading. As a result, you might experience a higher 
+startup delay (the time it takes for the program to launch and be ready for use).
+
+Based on our tests, enabling this feature could potentially double the additional time cost
+incurred by the agent during the boot-up stage. This might also lead to delays in class 
+loading during runtime.

docs/menu.yml

@@ -34,6 +34,8 @@ catalog:
         path: "/en/setup/service-agent/java-agent/tls"
       - name: "Token Authentication"
         path: "/en/setup/service-agent/java-agent/token-auth"
+      - name: "Work with other Java agents"
+        path: "/en/setup/service-agent/java-agent/re-transform"
       - name: "Manual APIs"
         catalog:
           - name: "Tracing APIs"

test/plugin/scenarios/retransform-class-scenario/configuration.yml

@@ -19,5 +19,6 @@ entryService: http://localhost:8080/case/retransform-class-scenario
 healthCheck: http://localhost:8080/case/healthCheck
 startScript: ./bin/startup.sh
 environment:
+  - SW_ENABLE_RETRANSFORM_SUPPORT=true
 dependencies:
 withPlugins: apm-spring-*.jar, apm-jdk-*.jar

test/plugin/scenarios/retransform-class-tomcat-scenario/configuration.yml

@@ -19,3 +19,5 @@ entryService: http://localhost:8080/retransform-class-tomcat-scenario/case/retra
 healthCheck: http://localhost:8080/retransform-class-tomcat-scenario/case/healthCheck
 dependencies:
 withPlugins: apm-spring-*.jar, apm-jdk-*.jar
+environment:
+  - CATALINA_OPTS="-Dskywalking.agent.enable_retransform_support=true"