Global opentelemetry guidance (#956)

Author: jack-berg

doc-snippets/api/build.gradle.kts

@@ -11,7 +11,8 @@ java {
 }
 
 dependencies {
-    implementation("io.opentelemetry:opentelemetry-api")
+    // TODO: revert version after 2.23.0 instrumentation release
+    implementation("io.opentelemetry:opentelemetry-api:1.57.0")
 
     implementation("io.opentelemetry.semconv:opentelemetry-semconv")
     implementation("io.opentelemetry.semconv:opentelemetry-semconv-incubating:1.37.0-alpha")

doc-snippets/api/src/main/java/otel/GlobalOpenTelemetryNativeInstrumentationUsage.java

@@ -0,0 +1,47 @@
+package otel;
+
+import io.opentelemetry.api.GlobalOpenTelemetry;
+import io.opentelemetry.api.OpenTelemetry;
+
+public class GlobalOpenTelemetryNativeInstrumentationUsage {
+
+  public static void globalOpenTelemetryUsage(OpenTelemetry openTelemetry) {
+    // Initialized with OpenTelemetry from java agent if present, otherwise no-op implementation.
+    MyClient client1 = new MyClientBuilder().build();
+
+    // Initialized with an explicit OpenTelemetry instance, overriding the java agent instance.
+    MyClient client2 = new MyClientBuilder().setOpenTelemetry(openTelemetry).build();
+  }
+
+  /**
+   * An example library with native OpenTelemetry instrumentation, initialized via {@link
+   * MyClientBuilder}.
+   */
+  public static class MyClient {
+    private final OpenTelemetry openTelemetry;
+
+    private MyClient(OpenTelemetry openTelemetry) {
+      this.openTelemetry = openTelemetry;
+    }
+
+    // ... library methods omitted
+  }
+
+  /** Builder for {@link MyClient}. */
+  public static class MyClientBuilder {
+    // OpenTelemetry defaults to the GlobalOpenTelemetry instance if set, e.g. by the java agent or
+    // by the application, else to a no-op implementation.
+    private OpenTelemetry openTelemetry = GlobalOpenTelemetry.getOrNoop();
+
+    /** Explicitly set the OpenTelemetry instance to use. */
+    public MyClientBuilder setOpenTelemetry(OpenTelemetry openTelemetry) {
+      this.openTelemetry = openTelemetry;
+      return this;
+    }
+
+    /** Build the client. */
+    public MyClient build() {
+      return new MyClient(openTelemetry);
+    }
+  }
+}

doc-snippets/api/src/main/java/otel/GlobalOpenTelemetryUsage.java

@@ -20,10 +20,10 @@ public class NoopUsage {
   private static final String SCOPE_NAME = "fully.qualified.name";
 
   public static void noopUsage() {
-    // Access the noop OpenTelemetry instance
+    // Access the no-op OpenTelemetry instance
     OpenTelemetry noopOpenTelemetry = OpenTelemetry.noop();
 
-    // Noop tracing
+    // No-op tracing
     Tracer noopTracer = OpenTelemetry.noop().getTracer(SCOPE_NAME);
     noopTracer
         .spanBuilder("span name")
@@ -33,7 +33,7 @@ public static void noopUsage() {
         .addEvent("event-name", Attributes.builder().put(WIDGET_COLOR, "red").build())
         .end();
 
-    // Noop metrics
+    // No-op metrics
     Attributes attributes = WIDGET_RED_CIRCLE;
     Meter noopMeter = OpenTelemetry.noop().getMeter(SCOPE_NAME);
     DoubleHistogram histogram = noopMeter.histogramBuilder("fully.qualified.histogram").build();
@@ -61,7 +61,7 @@ public static void noopUsage() {
         .gaugeBuilder("fully.qualified.gauge")
         .buildWithCallback(observable -> observable.record(10, attributes));
 
-    // Noop logs
+    // No-op logs
     Logger noopLogger = OpenTelemetry.noop().getLogsBridge().get(SCOPE_NAME);
     noopLogger
         .logRecordBuilder()

doc-snippets/api/src/main/java/otel/NoopUsage.java

@@ -11,6 +11,9 @@ java {
 }
 
 dependencies {
+    // TODO: delete after 2.23.0 instrumentation release
+    implementation("io.opentelemetry:opentelemetry-api:1.57.0")
+
     implementation("io.opentelemetry:opentelemetry-sdk")
     implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure")
 

doc-snippets/configuration/build.gradle.kts

@@ -0,0 +1,23 @@
+package otel;
+
+import io.opentelemetry.api.GlobalOpenTelemetry;
+import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;
+
+public class GlobalOpenTelemetryManualInstrumentationUsage {
+
+  public static void globalOpenTelemetryUsage() {
+    // If GlobalOpenTelemetry is already set, e.g. by the java agent, use it.
+    // Else, initialize an OpenTelemetry SDK instance and use it.
+    OpenTelemetry openTelemetry =
+        GlobalOpenTelemetry.isSet() ? GlobalOpenTelemetry.get() : initializeOpenTelemetry();
+
+    // Install into manual instrumentation. This may involve setting as a singleton in the
+    // application's dependency injection framework.
+  }
+
+  /** Initialize OpenTelemetry SDK using autoconfiguration. */
+  public static OpenTelemetry initializeOpenTelemetry() {
+    return AutoConfiguredOpenTelemetrySdk.initialize().getOpenTelemetrySdk();
+  }
+}

doc-snippets/configuration/src/main/java/otel/GlobalOpenTelemetryManualInstrumentationUsage.java

@@ -82,7 +82,7 @@ private synchronized String getToken() {
   }
 
   private static String refreshToken(String username, String password) {
-    // For a production scenario, this would be replaced with out-of-band request to exchange
+    // For a production scenario, this would be replaced with an out-of-band request to exchange
     // username / password for bearer token.
     return "abc123";
   }