Runtime attachment additions (#354)

* Add tests on runtime attachment

* Add log when agent is disabled with otel.javaagent.enabled property or OTEL_JAVAAGENT_ENABLED environment variable

* Do not try to attach if agent is already attached

* Do not try to attach if attachment is not asked for the main thread

* Add log if an unexpected issue has happened during attachment

* Add javadoc

* Add information to the Readme

* Format javadoc

* Fix mistake in Readme

* Update runtime-attach/build.gradle.kts

Co-authored-by: Trask Stalnaker <[email protected]>

* Update runtime-attach/README.md

Co-authored-by: Trask Stalnaker <[email protected]>

* Update runtime-attach/src/main/java/io/opentelemetry/contrib/attach/RuntimeAttach.java

Co-authored-by: Trask Stalnaker <[email protected]>

* Update runtime-attach/src/main/java/io/opentelemetry/contrib/attach/RuntimeAttach.java

Co-authored-by: Trask Stalnaker <[email protected]>

* Update runtime-attach/src/main/java/io/opentelemetry/contrib/attach/RuntimeAttach.java

Co-authored-by: Trask Stalnaker <[email protected]>

* Update runtime-attach/build.gradle.kts

Co-authored-by: Trask Stalnaker <[email protected]>

* Replace triple ``` by single `

* Log at debug level in shouldAttach() method

* Log at warn level if the runtime attachment is not requested from main thread

* Logger name in lower case as in OTel agent

* Add space in class Javadoc

* Add space in Readme

* Update Javadoc of method

* Update runtime-attach/src/main/java/io/opentelemetry/contrib/attach/RuntimeAttach.java

Co-authored-by: Trask Stalnaker <[email protected]>

* Don't attach if attachment is not requested from the main method

* Inline local variable

* Move opentelemetry-javaagent to dependency management

Co-authored-by: Trask Stalnaker <[email protected]>

Author: jeanbisutti

dependencyManagement/build.gradle.kts

@@ -58,6 +58,7 @@ val DEPENDENCY_SETS = listOf(
 )
 
 val DEPENDENCIES = listOf(
+    "io.opentelemetry.javaagent:opentelemetry-javaagent:1.14.0",
     "com.google.code.findbugs:annotations:3.0.1u2",
     "com.google.code.findbugs:jsr305:3.0.2",
     "com.squareup.okhttp3:okhttp:4.9.3",

runtime-attach/README.md

@@ -1,3 +1,30 @@
+# Runtime attachment
+
+If you can't update the JVM arguments to attach the [OpenTelemetry Java agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation) (_-javaagent:path/to/opentelemetry-javaagent.jar_), this project allows you to do attachment programmatically.
+
+The `io.opentelemetry.contrib.attach.RuntimeAttach` class has an `attachJavaagentToCurrentJVM` method allowing to trigger the attachment of the OTel agent for Java.
+
+The attachment will not be initiated in the following cases:
+* The `otel.javaagent.enabled` property is set to `false`
+* The `OTEL_JAVAAGENT_ENABLED` environment variable is set to `false`
+* The attachment is not requested from the _main_ thread
+* The attachment is not requested from the `public static void main(String[] args)` method
+* The agent is already attached
+
+_The attachment must be requested at the beginning of the `public static void main(String[] args)` method._ We give below an example for Spring Boot applications:
+
+```java
+@SpringBootApplication
+public class SpringBootApp {
+
+    public static void main(String[] args) {
+        RuntimeAttach.attachJavaagentToCurrentJVM();
+        SpringApplication.run(SpringBootApp.class, args);
+    }
+
+}
+```
+
 ## Component owners
 
 - [Nikita Salnikov-Tarnovski](https://github.com/iNikem), Splunk

runtime-attach/build.gradle.kts

@@ -11,4 +11,15 @@ dependencies {
 
   // Used by byte-buddy but not brought in as a transitive dependency.
   compileOnly("com.google.code.findbugs:annotations")
+
+  testImplementation("io.opentelemetry.javaagent:opentelemetry-javaagent")
+  testImplementation("io.opentelemetry:opentelemetry-extension-annotations")
+  testImplementation("org.junit.jupiter:junit-jupiter-api")
+  testImplementation("org.junit-pioneer:junit-pioneer")
+  testImplementation("org.assertj:assertj-core")
+}
+
+tasks.test {
+  useJUnitPlatform()
+  setForkEvery(1) // One JVM by test class to avoid a test class launching a runtime attachment influences the behavior of another test class
 }

runtime-attach/src/main/java/io/opentelemetry/contrib/attach/RuntimeAttach.java

@@ -7,22 +7,99 @@
 
 import java.io.File;
 import java.lang.management.ManagementFactory;
+import java.util.logging.Logger;
 import net.bytebuddy.agent.ByteBuddyAgent;
 
+/** This class allows you to attach the OpenTelemetry Java agent at runtime. */
 public final class RuntimeAttach {
 
+  private static final Logger logger = Logger.getLogger(RuntimeAttach.class.getName());
+  private static final String AGENT_ENABLED_PROPERTY = "otel.javaagent.enabled";
+  private static final String AGENT_ENABLED_ENV_VAR = "OTEL_JAVAAGENT_ENABLED";
+  static final String MAIN_METHOD_CHECK_PROP =
+      "otel.javaagent.testing.runtime-attach.main-method-check";
+
+  /**
+   * Attach the OpenTelemetry Java agent to the current JVM. The attachment must be requested at the
+   * beginning of the main method.
+   */
   public static void attachJavaagentToCurrentJVM() {
-    if (agentIsDisabled()) {
+    if (!shouldAttach()) {
       return;
     }
+
     File javaagentFile = AgentFileLocator.locateAgentFile();
     ByteBuddyAgent.attach(javaagentFile, getPid());
+
+    if (!agentIsAttached()) {
+      logger.warning("Agent was not attached. An unexpected issue has happened.");
+    }
+  }
+
+  private static boolean shouldAttach() {
+    if (agentIsDisabledWithProp()) {
+      logger.fine("Agent was disabled with " + AGENT_ENABLED_PROPERTY + " property.");
+      return false;
+    }
+    if (agentIsDisabledWithEnvVar()) {
+      logger.fine("Agent was disabled with " + AGENT_ENABLED_ENV_VAR + " environment variable.");
+      return false;
+    }
+    if (agentIsAttached()) {
+      logger.fine("Agent is already attached. It is not attached a second time.");
+      return false;
+    }
+    if (mainMethodCheckIsEnabled() && !isMainThread()) {
+      logger.warning(
+          "Agent is not attached because runtime attachment was not requested from main thread.");
+      return false;
+    }
+    if (mainMethodCheckIsEnabled() && !isMainMethod()) {
+      logger.warning(
+          "Agent is not attached because runtime attachment was not requested from main method.");
+      return false;
+    }
+    return true;
+  }
+
+  private static boolean agentIsDisabledWithProp() {
+    String agentEnabledPropValue = System.getProperty(AGENT_ENABLED_PROPERTY);
+    return "false".equalsIgnoreCase(agentEnabledPropValue);
+  }
+
+  private static boolean agentIsDisabledWithEnvVar() {
+    String agentEnabledEnvVarValue = System.getenv(AGENT_ENABLED_ENV_VAR);
+    return "false".equals(agentEnabledEnvVarValue);
+  }
+
+  private static boolean agentIsAttached() {
+    try {
+      Class.forName("io.opentelemetry.javaagent.OpenTelemetryAgent", false, null);
+      return true;
+    } catch (ClassNotFoundException e) {
+      return false;
+    }
+  }
+
+  private static boolean mainMethodCheckIsEnabled() {
+    String mainThreadCheck = System.getProperty(MAIN_METHOD_CHECK_PROP);
+    return !"false".equals(mainThreadCheck);
+  }
+
+  private static boolean isMainThread() {
+    Thread currentThread = Thread.currentThread();
+    return "main".equals(currentThread.getName());
+  }
+
+  static boolean isMainMethod() {
+    StackTraceElement bottomOfStack = findBottomOfStack(Thread.currentThread());
+    String methodName = bottomOfStack.getMethodName();
+    return "main".equals(methodName);
   }
 
-  private static boolean agentIsDisabled() {
-    String enabledProperty =
-        System.getProperty("otel.javaagent.enabled", System.getenv("OTEL_JAVAAGENT_ENABLED"));
-    return "false".equals(enabledProperty);
+  private static StackTraceElement findBottomOfStack(Thread thread) {
+    StackTraceElement[] stackTrace = thread.getStackTrace();
+    return stackTrace[stackTrace.length - 1];
   }
 
   private static String getPid() {

runtime-attach/src/test/java/io/opentelemetry/contrib/attach/AbstractAttachmentTest.java

@@ -0,0 +1,21 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.contrib.attach;
+
+import io.opentelemetry.javaagent.shaded.io.opentelemetry.api.trace.Span;
+import org.junit.jupiter.api.BeforeAll;
+
+public class AbstractAttachmentTest {
+
+  @BeforeAll
+  static void disableMainThreadCheck() {
+    System.setProperty(RuntimeAttach.MAIN_METHOD_CHECK_PROP, "false");
+  }
+
+  boolean isAttached() {
+    return Span.current().getSpanContext().isValid();
+  }
+}

runtime-attach/src/test/java/io/opentelemetry/contrib/attach/AgentDisabledTest.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.contrib.attach;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import io.opentelemetry.extension.annotations.WithSpan;
+import org.junit.jupiter.api.Test;
+import org.junitpioneer.jupiter.SetEnvironmentVariable;
+import org.junitpioneer.jupiter.SetSystemProperty;
+
+public class AgentDisabledTest extends AbstractAttachmentTest {
+
+  @SetEnvironmentVariable(key = "OTEL_JAVAAGENT_ENABLED", value = "false")
+  @Test
+  void shouldNotAttachWhenAgentDisabledWithEnvVariable() {
+    RuntimeAttach.attachJavaagentToCurrentJVM();
+    verifyNoAttachment();
+  }
+
+  @WithSpan
+  void verifyNoAttachment() {
+    assertThat(isAttached()).as("Agent should not be attached").isFalse();
+  }
+
+  @SetSystemProperty(key = "otel.javaagent.enabled", value = "false")
+  @Test
+  void shouldNotAttachWhenAgentDisabledWithProperty() {
+    RuntimeAttach.attachJavaagentToCurrentJVM();
+    verifyNoAttachment();
+  }
+}

runtime-attach/src/test/java/io/opentelemetry/contrib/attach/RunTimeAttachBasicTest.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.contrib.attach;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import io.opentelemetry.extension.annotations.WithSpan;
+import org.junit.jupiter.api.Test;
+
+public class RunTimeAttachBasicTest extends AbstractAttachmentTest {
+
+  @Test
+  void shouldAttach() {
+    RuntimeAttach.attachJavaagentToCurrentJVM();
+    verifyAttachment();
+  }
+
+  @WithSpan
+  void verifyAttachment() {
+    assertThat(isAttached()).as("Agent should be attached").isTrue();
+  }
+}