Rename ComponentInstaller to AgentListener and add #order() method (#…

…3182)

* Rename ComponentInstaller to AgentListener and add #order() method

* Code review comments

* Update javaagent-tooling/src/main/java/io/opentelemetry/javaagent/tooling/SafeServiceLoader.java

Co-authored-by: Nikita Salnikov-Tarnovski <gnikem@gmail.com>

Co-authored-by: Nikita Salnikov-Tarnovski <gnikem@gmail.com>

instrumentation/oshi/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/oshi/OshiMetricsInstaller.java

@@ -7,18 +7,18 @@
 
 import com.google.auto.service.AutoService;
 import io.opentelemetry.instrumentation.api.config.Config;
-import io.opentelemetry.javaagent.spi.ComponentInstaller;
+import io.opentelemetry.javaagent.extension.AgentListener;
 import java.lang.reflect.Method;
 import java.util.Collections;
 
 /**
- * {@link ComponentInstaller} to enable oshi metrics during agent startup if oshi is present on the
+ * An {@link AgentListener} that enables oshi metrics during agent startup if oshi is present on the
  * system classpath.
  */
-@AutoService(ComponentInstaller.class)
-public class OshiMetricsInstaller implements ComponentInstaller {
+@AutoService(AgentListener.class)
+public class OshiMetricsInstaller implements AgentListener {
   @Override
-  public void afterByteBuddyAgent(Config config) {
+  public void afterAgent(Config config) {
     if (config.isInstrumentationEnabled(
         Collections.singleton("oshi"), /* defaultEnabled= */ true)) {
       try {

instrumentation/runtime-metrics/javaagent/src/main/java/io/opentelemetry/instrumentation/javaagent/runtimemetrics/RuntimeMetricsInstaller.java

@@ -9,14 +9,14 @@
 import io.opentelemetry.instrumentation.api.config.Config;
 import io.opentelemetry.instrumentation.runtimemetrics.GarbageCollector;
 import io.opentelemetry.instrumentation.runtimemetrics.MemoryPools;
-import io.opentelemetry.javaagent.spi.ComponentInstaller;
+import io.opentelemetry.javaagent.extension.AgentListener;
 import java.util.Collections;
 
-/** {@link ComponentInstaller} to enable runtime metrics during agent startup. */
-@AutoService(ComponentInstaller.class)
-public class RuntimeMetricsInstaller implements ComponentInstaller {
+/** An {@link AgentListener} that enables runtime metrics during agent startup. */
+@AutoService(AgentListener.class)
+public class RuntimeMetricsInstaller implements AgentListener {
   @Override
-  public void afterByteBuddyAgent(Config config) {
+  public void afterAgent(Config config) {
     if (config.isInstrumentationEnabled(
         Collections.singleton("runtime-metrics"), /* defaultEnabled= */ true)) {
       GarbageCollector.registerObservers();

javaagent-extension-api/src/main/java/io/opentelemetry/javaagent/extension/spi/AgentExtension.java → javaagent-extension-api/src/main/java/io/opentelemetry/javaagent/extension/AgentExtension.java

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.javaagent.extension.spi;
+package io.opentelemetry.javaagent.extension;
 
 import io.opentelemetry.javaagent.extension.instrumentation.InstrumentationModule;
 import net.bytebuddy.agent.builder.AgentBuilder;
@@ -16,7 +16,7 @@
  * <p>This is a service provider interface that requires implementations to be registered in a
  * provider-configuration file stored in the {@code META-INF/services} resource directory.
  */
-public interface AgentExtension {
+public interface AgentExtension extends Ordered {
 
   /**
    * Extend the passed {@code agentBuilder} with custom logic (e.g. instrumentation).
@@ -31,12 +31,4 @@ public interface AgentExtension {
    * human-readable: javaagent uses the extension name in its logs.
    */
   String extensionName();
-
-  /**
-   * Returns the order of adding extensions to the javaagent. Higher values are added later, for
-   * example: an extension with order=1 will run after an extension with order=0.
-   */
-  default int order() {
-    return 0;
-  }
 }

javaagent-extension-api/src/main/java/io/opentelemetry/javaagent/extension/AgentListener.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.javaagent.extension;
+
+import io.opentelemetry.instrumentation.api.config.Config;
+import io.opentelemetry.javaagent.instrumentation.api.InstrumentationContext;
+import java.lang.instrument.Instrumentation;
+import java.util.Map;
+import net.bytebuddy.agent.builder.AgentBuilder;
+
+/**
+ * {@link AgentListener} can be used to execute code before/after Java agent installation, for
+ * example to install any implementation providers that are used by instrumentations. For instance,
+ * this project uses this SPI to install OpenTelemetry SDK.
+ *
+ * <p>This is a service provider interface that requires implementations to be registered in a
+ * provider-configuration file stored in the {@code META-INF/services} resource directory.
+ */
+public interface AgentListener extends Ordered {
+
+  /**
+   * Runs before the {@link AgentBuilder} construction, before any instrumentation is added.
+   *
+   * <p>Execute only a minimal code because any classes loaded before the agent installation will
+   * have to be retransformed, which takes extra time, and more importantly means that fields can't
+   * be added to those classes - which causes {@link InstrumentationContext} to fall back to the
+   * less performant {@link Map} implementation for those classes.
+   */
+  default void beforeAgent(Config config) {}
+
+  /**
+   * Runs after instrumentations are added to {@link AgentBuilder} and after the agent is installed
+   * on an {@link Instrumentation}.
+   */
+  default void afterAgent(Config config) {}
+}

javaagent-extension-api/src/main/java/io/opentelemetry/javaagent/extension/Ordered.java

@@ -0,0 +1,16 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.javaagent.extension;
+
+public interface Ordered {
+  /**
+   * Returns the order of applying the SPI implementing this interface. Higher values are added
+   * later, for example: an SPI with order=1 will run after an SPI with order=0.
+   */
+  default int order() {
+    return 0;
+  }
+}

javaagent-extension-api/src/main/java/io/opentelemetry/javaagent/extension/instrumentation/InstrumentationModule.java

@@ -9,6 +9,7 @@
 import static net.bytebuddy.matcher.ElementMatchers.any;
 
 import io.opentelemetry.instrumentation.api.config.Config;
+import io.opentelemetry.javaagent.extension.Ordered;
 import io.opentelemetry.javaagent.extension.muzzle.ClassRef;
 import java.util.ArrayList;
 import java.util.Collections;
@@ -30,7 +31,7 @@
  * META-INF/services/} provider file is created for it to be picked up by the agent. See {@link
  * java.util.ServiceLoader} for more details.
  */
-public abstract class InstrumentationModule {
+public abstract class InstrumentationModule implements Ordered {
   private static final boolean DEFAULT_ENABLED =
       Config.get().getBooleanProperty("otel.instrumentation.common.default-enabled", true);
 
@@ -101,15 +102,6 @@ protected boolean defaultEnabled() {
     return DEFAULT_ENABLED;
   }
 
-  /**
-   * Returns the order of adding instrumentation modules to the javaagent. Higher values are added
-   * later, for example: an instrumentation module with order=1 will run after a module with
-   * order=0.
-   */
-  public int order() {
-    return 0;
-  }
-
   /**
    * Instrumentation modules can override this method to specify additional packages (or classes)
    * that should be treated as "library instrumentation" packages. Classes from those packages will