add start.async property for startup tuning (#2454)

* add start.async property for startup tuning

* add changelog, version introduced, and fix typo

Author: jackshirazi

CHANGELOG.asciidoc

@@ -53,6 +53,7 @@ endif::[]
 * Added support for Java/Jakarta WebSocket ServerEndpoint - {pull}2281[#2281]
 * Added support for setting the service name on Log4j2's EcsLayout - {pull}2296[#2296]
 * Print the used instrumentation groups when the application stops - {pull}2448[#2448]
+* Add `elastic.apm.start_async` property that makes the agent start on a non-premain/main thread - {pull}2454[#2454]
 
 [float]
 ===== Bug fixes

elastic-apm-agent/src/main/java/co/elastic/apm/agent/premain/AgentMain.java

@@ -90,7 +90,12 @@ public synchronized static void init(String agentArguments, Instrumentation inst
         if (delayAgentInitMs > 0) {
             delayAndInitAgentAsync(agentArguments, instrumentation, premain, delayAgentInitMs);
         } else {
-            loadAndInitializeAgent(agentArguments, instrumentation, premain);
+            String startAgentAsyncProperty = System.getProperty("elastic.apm.start_async");
+            if (startAgentAsyncProperty != null) {
+                delayAndInitAgentAsync(agentArguments, instrumentation, premain, 0);
+            } else {
+                loadAndInitializeAgent(agentArguments, instrumentation, premain);
+            }
         }
     }
 
@@ -119,7 +124,9 @@ private static void delayAndInitAgentAsync(final String agentArguments, final In
             public void run() {
                 try {
                     synchronized (AgentMain.class) {
-                        Thread.sleep(delayAgentInitMs);
+                        if (delayAgentInitMs > 0) {
+                            Thread.sleep(delayAgentInitMs);
+                        }
                         loadAndInitializeAgent(agentArguments, instrumentation, premain);
                     }
                 } catch (InterruptedException e) {

elastic-apm-agent/src/main/java/co/elastic/apm/agent/premain/package-info.java

@@ -29,9 +29,10 @@
  *     </li>
  *     <li>
  *         load the {@code co.elastic.apm.agent.bci.ElasticApmAgent} class and execute the agent initialization process
- *         <b>through reflection</b>. This can be done synchronously, blocking the bootstrapping thread, or
- *         asynchronously on a different thread after some delay, that may be configured through the
- *         {@code elastic.apm.delay_agent_premain_ms} System property.
+ *         <b>through reflection</b>. This can be done synchronously, blocking the bootstrapping thread (default); or
+ *         asynchronously on a different thread with the {@code elastic.apm.start_async} System property (since 1.29.0);
+ *         or asynchronously on a different thread after some delay, by configuring the
+ *         {@code elastic.apm.delay_agent_premain_ms} System property with some positive value.
  *     </li>
  * </ul>
  */