diff --git a/doc-snippets/api/build.gradle.kts b/doc-snippets/api/build.gradle.kts index 9f3f7d67d9..65fb0dc050 100644 --- a/doc-snippets/api/build.gradle.kts +++ b/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") diff --git a/doc-snippets/api/src/main/java/otel/GlobalOpenTelemetryNativeInstrumentationUsage.java b/doc-snippets/api/src/main/java/otel/GlobalOpenTelemetryNativeInstrumentationUsage.java new file mode 100644 index 0000000000..58c80e313f --- /dev/null +++ b/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); + } + } +} diff --git a/doc-snippets/api/src/main/java/otel/GlobalOpenTelemetryUsage.java b/doc-snippets/api/src/main/java/otel/GlobalOpenTelemetryUsage.java deleted file mode 100644 index b302a9bfe3..0000000000 --- a/doc-snippets/api/src/main/java/otel/GlobalOpenTelemetryUsage.java +++ /dev/null @@ -1,16 +0,0 @@ -package otel; - -import io.opentelemetry.api.GlobalOpenTelemetry; -import io.opentelemetry.api.OpenTelemetry; - -public class GlobalOpenTelemetryUsage { - - public static void openTelemetryUsage(OpenTelemetry openTelemetry) { - // Set the GlobalOpenTelemetry instance as early in the application lifecycle as possible - // Set must only be called once. Calling multiple times raises an exception. - GlobalOpenTelemetry.set(openTelemetry); - - // Get the GlobalOpenTelemetry instance. - openTelemetry = GlobalOpenTelemetry.get(); - } -} diff --git a/doc-snippets/api/src/main/java/otel/NoopUsage.java b/doc-snippets/api/src/main/java/otel/NoopUsage.java index 608ba5d52f..28d0414824 100644 --- a/doc-snippets/api/src/main/java/otel/NoopUsage.java +++ b/doc-snippets/api/src/main/java/otel/NoopUsage.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() diff --git a/doc-snippets/configuration/build.gradle.kts b/doc-snippets/configuration/build.gradle.kts index 433ceb6283..a245211870 100644 --- a/doc-snippets/configuration/build.gradle.kts +++ b/doc-snippets/configuration/build.gradle.kts @@ -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") diff --git a/doc-snippets/configuration/src/main/java/otel/GlobalOpenTelemetryManualInstrumentationUsage.java b/doc-snippets/configuration/src/main/java/otel/GlobalOpenTelemetryManualInstrumentationUsage.java new file mode 100644 index 0000000000..67a2ea9c5e --- /dev/null +++ b/doc-snippets/configuration/src/main/java/otel/GlobalOpenTelemetryManualInstrumentationUsage.java @@ -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(); + } +} diff --git a/doc-snippets/configuration/src/main/java/otel/OtlpAuthenticationConfig.java b/doc-snippets/configuration/src/main/java/otel/OtlpAuthenticationConfig.java index 769880616a..568282b498 100644 --- a/doc-snippets/configuration/src/main/java/otel/OtlpAuthenticationConfig.java +++ b/doc-snippets/configuration/src/main/java/otel/OtlpAuthenticationConfig.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"; }