getOrNoop, getOrSet

Author: jack-berg

api/all/src/main/java/io/opentelemetry/api/GlobalOpenTelemetry.java

@@ -26,21 +26,36 @@
 import javax.annotation.concurrent.ThreadSafe;
 
 /**
- * A global singleton for the entrypoint to telemetry functionality for tracing, metrics and
- * baggage.
+ * Provides access to a global singleton {@link OpenTelemetry} instance.
  *
- * <p>If using the OpenTelemetry SDK, you may want to instantiate the {@link OpenTelemetry} to
- * provide configuration, for example of {@code Resource} or {@code Sampler}. See {@code
- * OpenTelemetrySdk} and {@code OpenTelemetrySdk.builder} for information on how to construct the
- * SDK's {@link OpenTelemetry} implementation.
+ * <p>WARNING: To avoid inherent complications around initialization ordering, it's best-practice to
+ * pass around instances of {@link OpenTelemetry} rather than using {@link GlobalOpenTelemetry}.
+ * However, the OpenTelemetry javagent makes the {@link OpenTelemetry} instance it installs
+ * available via {@link GlobalOpenTelemetry}. As a result, {@link GlobalOpenTelemetry} plays an
+ * important role in native instrumentation and application custom instrumentation.
  *
- * <p>WARNING: Due to the inherent complications around initialization order involving this class
- * and its single global instance, we strongly recommend *not* using GlobalOpenTelemetry unless you
- * have a use-case that absolutely requires it. Please favor using instances of OpenTelemetry
- * wherever possible.
+ * <p>Native instrumentation should use {@link #getOrNoop()} as the default {@link OpenTelemetry}
+ * instance, and expose APIs for setting a custom instance. This results in the following behavior:
  *
- * <p>If you are using the OpenTelemetry javaagent, it is generally best to only call
- * GlobalOpenTelemetry.get() once, and then pass the resulting reference where you need to use it.
+ * <ul>
+ *   <li>If the OpenTelemetry javaagent is installed, the native instrumentation will default to the
+ *       {@link OpenTelemetry} it installs.
+ *   <li>If the OpenTelemetry javaagent is not installed, the native instrumentation will default to
+ *       a noop instance.
+ *   <li>If the user explicitly sets a custom instance, it will be used, regardless of whether or
+ *       not the OpenTelemetry javaagent is installed.
+ * </ul>
+ *
+ * <p>Applications with custom instrumentation should call {@link #getOrSet(Supplier)} once during
+ * initialization, and pass the resulting instance around manually (or with dependency injection) to
+ * install custom instrumentation. This results in the following behavior:
+ *
+ * <ul>
+ *   <li>If the OpenTelemetry javaagent is installed, custom instrumentation will use the {@link
+ *       OpenTelemetry} it installs.
+ *   <li>If the OpenTelemetry javaagent is not installed, custom instrumentation will use the {@link
+ *       OpenTelemetry} instance returned by {@link Supplier} passed to {@link #getOrSet(Supplier)}.
+ * </ul>
  *
  * @see TracerProvider
  * @see ContextPropagators
@@ -68,10 +83,68 @@ public final class GlobalOpenTelemetry {
   private GlobalOpenTelemetry() {}
 
   /**
-   * Returns the registered global {@link OpenTelemetry}.
+   * Returns the registered global {@link OpenTelemetry} if set, or else {@link
+   * OpenTelemetry#noop()}.
+   *
+   * <p>NOTE: if the global instance is set, the response is obfuscated to prevent callers from
+   * casting to SDK implementation instances and inappropriately accessing non-instrumentation APIs.
    *
-   * @throws IllegalStateException if a provider has been specified by system property using the
-   *     interface FQCN but the specified provider cannot be found.
+   * <p>NOTE: This does not result in the {@link #set(OpenTelemetry)} side effects of {@link
+   * #get()}.
+   *
+   * <p>Native instrumentation should use this method to initialize their default {@link
+   * OpenTelemetry} instance. See class javadoc for more details.
+   */
+  public static OpenTelemetry getOrNoop() {
+    synchronized (mutex) {
+      return globalOpenTelemetry != null ? globalOpenTelemetry : OpenTelemetry.noop();
+    }
+  }
+
+  /**
+   * Returns the registered global {@link OpenTelemetry} if set, or else calls {@link
+   * #set(Supplier)} with the {@code supplier}.
+   *
+   * <p>NOTE: if the global instance is set, the response is obfuscated to prevent callers from
+   * casting to SDK implementation instances and inappropriately accessing non-instrumentation APIs.
+   *
+   * <p>NOTE: This does not result in the {@link #set(OpenTelemetry)} side effects of {@link
+   * #get()}.
+   *
+   * <p>Application custom instrumentation should use this method during initialization. See class
+   * javadoc for more details.
+   */
+  public static OpenTelemetry getOrSet(Supplier<OpenTelemetry> supplier) {
+    synchronized (mutex) {
+      if (globalOpenTelemetry == null) {
+        OpenTelemetry openTelemetry = supplier.get();
+        set(openTelemetry);
+        return openTelemetry;
+      }
+      return globalOpenTelemetry;
+    }
+  }
+
+  /**
+   * Returns the registered global {@link OpenTelemetry} if set, else calls {@link
+   * GlobalOpenTelemetry#set(OpenTelemetry)} with a no-op {@link OpenTelemetry} instance and returns
+   * that.
+   *
+   * <p>NOTE: all returned instanced are obfuscated to prevent callers from casting to SDK
+   * implementation instances and inappropriately accessing non-instrumentation APIs.
+   *
+   * <p>Native instrumentations should use {@link #getOrNoop()} instad. See class javadoc for more
+   * details.
+   *
+   * <p>Application custom instrumentation should use {@link #getOrSet(Supplier)} instead. See class
+   * javadoc for more details.
+   *
+   * <p>If the global instance has not been set, and {@code
+   * io.opentelemetry:opentelemetry-sdk-extension-autoconfigure} is present, and {@value
+   * GLOBAL_AUTOCONFIGURE_ENABLED_PROPERTY} is {@code true}, the global instance will be set to an
+   * autoconfigured instance instead of {@link OpenTelemetry#noop()}.
+   *
+   * @throws IllegalStateException if autoconfigure initialization is triggered and fails.
    */
   public static OpenTelemetry get() {
     OpenTelemetry openTelemetry = globalOpenTelemetry;
@@ -134,20 +207,6 @@ public static void set(Supplier<OpenTelemetry> supplier) {
     }
   }
 
-  /**
-   * Evaluate if the global instance has been set without the side effects of {@link #get()}.
-   *
-   * <p>This is useful for evaluating if any code, like the OpenTelemetry javaagent, has previously
-   * set the global instance while preserving the ability to set it.
-   *
-   * @return true if the global instance has been set, false otherwise.
-   */
-  public static boolean isSet() {
-    synchronized (mutex) {
-      return globalOpenTelemetry != null;
-    }
-  }
-
   /** Returns the globally registered {@link TracerProvider}. */
   public static TracerProvider getTracerProvider() {
     return get().getTracerProvider();

api/testing-internal/src/main/java/io/opentelemetry/api/testing/internal/AbstractOpenTelemetryTest.java

@@ -14,6 +14,8 @@
 import io.opentelemetry.api.metrics.MeterProvider;
 import io.opentelemetry.api.trace.TracerProvider;
 import io.opentelemetry.context.propagation.ContextPropagators;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.function.Supplier;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Test;
@@ -86,9 +88,9 @@ void independentNonGlobalPropagators() {
 
   @Test
   void setThenSet() {
-    assertThat(GlobalOpenTelemetry.isSet()).isFalse();
+    assertThat(GlobalOpenTelemetry.getOrNoop()).isSameAs(OpenTelemetry.noop());
     setOpenTelemetry();
-    assertThat(GlobalOpenTelemetry.isSet()).isTrue();
+    assertThat(GlobalOpenTelemetry.getOrNoop()).isNotSameAs(OpenTelemetry.noop());
     assertThatThrownBy(() -> GlobalOpenTelemetry.set(getOpenTelemetry()))
         .isInstanceOf(IllegalStateException.class)
         .hasMessageContaining("GlobalOpenTelemetry.set has already been called")
@@ -97,7 +99,7 @@ void setThenSet() {
 
   @Test
   void getThenSet() {
-    assertThat(GlobalOpenTelemetry.isSet()).isFalse();
+    assertThat(GlobalOpenTelemetry.getOrNoop()).isSameAs(OpenTelemetry.noop());
     // Calling GlobalOpenTelemetry.get() has the side affect of setting GlobalOpenTelemetry to an
     // (obfuscated) noop.
     // Call GlobalOpenTelemetry.get() using a utility method so we can later assert it was
@@ -109,7 +111,7 @@ void getThenSet() {
                     .isEqualTo("io.opentelemetry.api.GlobalOpenTelemetry$ObfuscatedOpenTelemetry"))
         .extracting("delegate")
         .isSameAs(OpenTelemetry.noop());
-    assertThat(GlobalOpenTelemetry.isSet()).isTrue();
+    assertThat(GlobalOpenTelemetry.getOrNoop()).isNotSameAs(OpenTelemetry.noop());
     assertThatThrownBy(() -> GlobalOpenTelemetry.set(getOpenTelemetry()))
         .isInstanceOf(IllegalStateException.class)
         .hasMessageContaining("GlobalOpenTelemetry.set has already been called")
@@ -120,6 +122,51 @@ private static OpenTelemetry getGlobalOpenTelemetry() {
     return GlobalOpenTelemetry.get();
   }
 
+  @Test
+  void getOrNoop() {
+    // Should be able to call getOrNoop multiple times without side effect and later call set.
+    assertThat(GlobalOpenTelemetry.getOrNoop()).isSameAs(OpenTelemetry.noop());
+    assertThat(GlobalOpenTelemetry.getOrNoop()).isSameAs(OpenTelemetry.noop());
+    setOpenTelemetry();
+    assertThat(GlobalOpenTelemetry.getOrNoop()).isNotSameAs(OpenTelemetry.noop());
+  }
+
+  @Test
+  void getOrSet_NotPreviouslySet() {
+    AtomicInteger supplierCallCount = new AtomicInteger();
+    Supplier<OpenTelemetry> supplier =
+        () -> {
+          supplierCallCount.incrementAndGet();
+          return OpenTelemetry.noop();
+        };
+
+    assertThat(GlobalOpenTelemetry.getOrSet(supplier)).isSameAs(OpenTelemetry.noop());
+    assertThat(supplierCallCount.get()).isEqualTo(1);
+
+    // The second time getOrSet is called, we get an obfuscated instance
+    assertThat(GlobalOpenTelemetry.getOrSet(supplier).getClass().getName())
+        .isEqualTo("io.opentelemetry.api.GlobalOpenTelemetry$ObfuscatedOpenTelemetry");
+    assertThat(supplierCallCount.get()).isEqualTo(1);
+  }
+
+  @Test
+  void getOrSet_PreviouslySet() {
+    setOpenTelemetry();
+
+    AtomicInteger supplierCallCount = new AtomicInteger();
+    Supplier<OpenTelemetry> supplier =
+        () -> {
+          supplierCallCount.incrementAndGet();
+          return OpenTelemetry.noop();
+        };
+
+    assertThat(GlobalOpenTelemetry.getOrSet(supplier).getClass().getName())
+        .isEqualTo("io.opentelemetry.api.GlobalOpenTelemetry$ObfuscatedOpenTelemetry");
+    assertThat(GlobalOpenTelemetry.getOrSet(supplier).getClass().getName())
+        .isEqualTo("io.opentelemetry.api.GlobalOpenTelemetry$ObfuscatedOpenTelemetry");
+    assertThat(supplierCallCount.get()).isEqualTo(0);
+  }
+
   @Test
   void toString_noop_Valid() {
     assertThat(getOpenTelemetry().toString())

docs/apidiffs/current_vs_latest/opentelemetry-api.txt

@@ -1,4 +1,5 @@
 Comparing source compatibility of opentelemetry-api-1.57.0-SNAPSHOT.jar against opentelemetry-api-1.56.0.jar
 ***  MODIFIED CLASS: PUBLIC FINAL io.opentelemetry.api.GlobalOpenTelemetry  (not serializable)
 	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
-	+++  NEW METHOD: PUBLIC(+) STATIC(+) boolean isSet()
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.api.OpenTelemetry getOrNoop()
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.api.OpenTelemetry getOrSet(java.util.function.Supplier<io.opentelemetry.api.OpenTelemetry>)