Native and manual instrumentation guidance for GlobalOpenTelemetry

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 noop 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 noop.
+    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

@@ -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,25 @@
+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();
+  }
+}