Update OpenTelemetry docs for Java v8 (#12209)

* Update OTel docs for Java v8

* Apply suggestions from code review

Co-authored-by: Alex Krawiec <[email protected]>

---------

Co-authored-by: Alex Krawiec <[email protected]>

Author: adinauer

docs/platforms/java/common/tracing/instrumentation/opentelemetry.mdx

@@ -7,6 +7,10 @@ sidebar_order: 20
 
 There are multiple ways to configure your [OpenTelemetry SDK](https://opentelemetry.io/) and send traces and spans to Sentry. They're described below.
 
+<PlatformSection supported={["java.spring", "java.spring-boot"]} notSupported={["java"]}>
+If you're unsure whether to use the Java Agent, please have a look at [what the OpenTelemetry SDK has to say about this](https://opentelemetry.io/docs/zero-code/java/spring-boot-starter/).
+</PlatformSection>
+
 ## Using `sentry-opentelemetry-agent` With Auto Initialization
 
 If you use `sentry-opentelemetry-agent`, it will look for `SENTRY_DSN` and `SENTRY_PROPERTIES_FILE` environment variables to be defined, and then initialize Sentry automatically. You'll just need to configure your `DSN` and `tracesSampleRate`.
@@ -49,7 +53,7 @@ You may also disable automatic initialization of Sentry in `sentry-opentelemetry
 
 ## Using OpenTelemetry Without Any Java Agent
 
-If the Java Agent approach isn't for you, you can manually initialize OpenTelemetry. We have a separate dependency for this use case that allows you to reuse classes used by `sentry-opentelemetry-agent`.
+If the Java Agent approach isn't for you, you can manually initialize OpenTelemetry. We have a separate dependency for this use case.
 
 ### Install
 

docs/platforms/java/migration/7.x-to-8.0.mdx

@@ -109,16 +109,6 @@ If you've not been using the Sentry OpenTelemetry agent before, you can add `sen
 - Please use `sentry.properties` or environment variables to configure the SDK as the agent is now in charge of initializing the SDK and options coming from things like logging integrations or our Spring Boot integration will not take effect.
 - You may find the [docs page](https://docs.sentry.io/platforms/java/tracing/instrumentation/opentelemetry/#using-sentry-opentelemetry-agent-with-auto-initialization) useful.
 
-If you want to skip auto initialization of the SDK performed by the agent, please follow the steps above and set the environment variable `SENTRY_AUTO_INIT` to `false` then add the following to your `Sentry.init`:
-
-```
-Sentry.init(options -> {
-  options.setDsn(...);
-  OpenTelemetryUtil.applyOpenTelemetryOptions(options);
-  ...
-});
-```
-
-If you're using our Spring Boot integration, it will automatically detect our OpenTelemetry agent and take care of configuring the SDK for you.
+If you want to skip auto initialization of the SDK performed by the agent, please follow the steps above and set the environment variable `SENTRY_AUTO_INIT` to `false`, then use `Sentry.init` as usual.
 
 We've added more sample applications that showcase how to combine Sentry and OpenTelemetry (https://github.com/getsentry/sentry-java/tree/8.x.x/sentry-samples).

platform-includes/performance/opentelemetry-install/with-java-agent/without-auto-init/java.mdx

@@ -1,7 +1 @@
 You can download the latest version of the `sentry-opentelemetry-agent-{{@inject packages.version('sentry.java.opentelemetry-agent') }}.jar` from [MavenCentral](https://search.maven.org/artifact/io.sentry/sentry-opentelemetry-agent). It's also available as a `ZIP` containing the `JAR` used on this page on [GitHub](https://github.com/getsentry/sentry-java/releases/).
-
-To ensure errors are properly linked to transactions that were created by the OpenTelemetry integration, you need an additional dependency:
-
-```groovy {tabTitle:Gradle}
-implementation 'io.sentry:sentry-opentelemetry-core:{{@inject packages.version('sentry.java.opentelemetry-core', '6.9.2') }}'
-```

platform-includes/performance/opentelemetry-install/without-java-agent/java.mdx

@@ -1,5 +1,14 @@
-In addition to OpenTelemetry dependencies and your typical Sentry dependencies, you will need to add `sentry-opentelemetry-core` as a dependency:
+In addition to your typical Sentry dependencies, you will need to add `sentry-opentelemetry-agentless` as a dependency:
 
 ```groovy {tabTitle:Gradle}
-implementation 'io.sentry:sentry-opentelemetry-core:{{@inject packages.version('sentry.java.opentelemetry-core', '6.9.2') }}'
+implementation 'io.sentry:sentry-opentelemetry-agentless:{{@inject packages.version('sentry.java.opentelemetry-agentless', '8.0.0') }}'
 ```
+```xml {tabTitle:Maven}
+<dependency>
+    <groupId>io.sentry</groupId>
+    <artifactId>sentry-opentelemetry-agentless</artifactId>
+    <version>{{@inject packages.version('sentry.java.opentelemetry-agentless', '8.0.0') }}</version>
+</dependency>
+```
+
+Please note, if you're using Spring Boot, there's a separate `sentry-opentelemetry-agentless-spring` dependency. You can <PlatformLink to="/guides/spring-boot/tracing/instrumentation/opentelemetry/">find out more here</PlatformLink>.

platform-includes/performance/opentelemetry-install/without-java-agent/java.spring-boot.mdx

@@ -0,0 +1,12 @@
+In addition to the Sentry Spring Boot SDK, you will need to add `sentry-opentelemetry-agentless-spring` as a dependency:
+
+```groovy {tabTitle:Gradle}
+implementation 'io.sentry:sentry-opentelemetry-agentless-spring:{{@inject packages.version('sentry.java.opentelemetry-agentless-spring', '8.0.0') }}'
+```
+```xml {tabTitle:Maven}
+<dependency>
+    <groupId>io.sentry</groupId>
+    <artifactId>sentry-opentelemetry-agentless-spring</artifactId>
+    <version>{{@inject packages.version('sentry.java.opentelemetry-agentless-spring', '8.0.0') }}</version>
+</dependency>
+```

platform-includes/performance/opentelemetry-setup/with-java-agent/exporter-messages/java.mdx

@@ -1,4 +1,4 @@
-If you're using `sentry-opentelemetry-agent` but don't need to use OpenTelemetry exporters, add
+If you're not using any OpenTelemetry exporters besides Sentry, add
 the following environment variables to turn off exporters and stop receiving error messages about
 servers not being reachable in the logs.
 
@@ -7,6 +7,7 @@ Example log message:
 ```
 ERROR io.opentelemetry.exporter.internal.grpc.OkHttpGrpcExporter - Failed to export spans. The request could not be executed. Full error message: Failed to connect to localhost/[0:0:0:0:0:0:0:1]:4317
 ERROR io.opentelemetry.exporter.internal.grpc.OkHttpGrpcExporter - Failed to export metrics. The request could not be executed. Full error message: Failed to connect to localhost/[0:0:0:0:0:0:0:1]:4317
+ERROR io.opentelemetry.exporter.internal.http.HttpExporter - Failed to export logs. The request could not be executed. Full error message: Failed to connect to localhost/[0:0:0:0:0:0:0:1]:4318
 ```
 
 #### Traces
@@ -16,3 +17,7 @@ To turn off traces exporting, set `OTEL_TRACES_EXPORTER=none` as an environment
 #### Metrics
 
 To turn off metrics exporting, set `OTEL_METRICS_EXPORTER=none` as an environment variable per [OpenTelemetry GitHub](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure#otlp-exporter-span-metric-and-log-exporters).
+
+#### Logs
+
+To turn off log exporting, set `OTEL_LOGS_EXPORTER=none` as an environment variable per [OpenTelemetry GitHub](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure#otlp-exporter-span-metric-and-log-exporters).

platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/debugging/java.spring-boot.mdx

@@ -1,4 +1,4 @@
 To enable debug logging for Sentry, set `SENTRY_DEBUG=true` as an environment variable or
 add `sentry.debug=true` to your `application.properties`.
 
-To show debug output for OpenTelemetry, add `-Dotel.javaagent.debug=true` to the command.
+To show debug output for OpenTelemetry, add `-Dotel.javaagent.debug=true` to the `java` command.

platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/java.mdx

@@ -1,28 +1,26 @@
-If you're not using the auto initialization provided by `sentry-opentelemetry-agent` (`SENTRY_AUTO_INIT=false`), you have to set the `instrumenter` option to `otel`. This disables all Sentry instrumentation and uses the chosen OpenTelemetry tracers for creating spans instead. To ensure errors are properly linked to transactions that were created by the OpenTelemetry integration, add the `OpenTelemetryLinkErrorEventProcessor`:
+This `java` command shows how to run your application using `sentry-opentelemetry-agent`:
 
 
+```bash
+SENTRY_AUTO_INIT=false java -javaagent:sentry-opentelemetry-agent-{{@inject packages.version('sentry.java.opentelemetry-agent') }}.jar -jar your-application.jar
+```
+
+You can combine this with a Sentry integration, that performs the initialization for you or call `Sentry.init` manually:
+
 ```java {tabTitle: Java}
-import io.sentry.Instrumenter;
 import io.sentry.Sentry;
-import io.sentry.opentelemetry.OpenTelemetryLinkErrorEventProcessor;
 
 Sentry.init(options -> {
   options.setDsn("___PUBLIC_DSN___");
   options.setTracesSampleRate(1.0);
-  options.setInstrumenter(Instrumenter.OTEL);
-  options.addEventProcessor(new OpenTelemetryLinkErrorEventProcessor());
 });
 ```
 
 ```kotlin {tabTitle: Kotlin}
-import io.sentry.Instrumenter
 import io.sentry.Sentry
-import io.sentry.opentelemetry.OpenTelemetryLinkErrorEventProcessor
 
 Sentry.init { options ->
   options.dsn = "___PUBLIC_DSN___"
   options.tracesSampleRate = 1.0
-  options.instrumenter = Instrumenter.OTEL
-  options.addEventProcessor(OpenTelemetryLinkErrorEventProcessor())
 }
 ```

platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/java.spring-boot.mdx

@@ -1,12 +1,19 @@
-If you're not using the auto initialization provided by `sentry-opentelemetry-agent` (`SENTRY_AUTO_INIT=false`), you have to
-set the `instrumenter` option to `otel`. This disables all Sentry instrumentation and uses the chosen OpenTelemetry tracers for creating spans instead:
+This `java` command shows how to run your application using `sentry-opentelemetry-agent`:
 
 
-```properties {filename:application.properties}
+```bash
+SENTRY_AUTO_INIT=false java -javaagent:sentry-opentelemetry-agent-{{@inject packages.version('sentry.java.opentelemetry-agent') }}.jar -jar your-application.jar
+```
+
+The Spring Boot Sentry SDK will take care of initializing Sentry, just make sure a `tracesSampleRate` has been set:
+
+```properties {tabTitle: application.properties}
 sentry.dsn=___PUBLIC_DSN___
 sentry.traces-sample-rate=1.0
-# enable this to see more logs
-sentry.debug=false
-# set the instrumenter to use OpenTelemetry instead of Sentry
-sentry.instrumenter=otel
+```
+
+```yaml {tabTitle: application.yml}
+sentry:
+    dsn: ___PUBLIC_DSN___
+    traces-sample-rate: 1.0
 ```

platform-includes/performance/opentelemetry-setup/without-java-agent/java.mdx

@@ -1,75 +1,61 @@
 #### Initializing OpenTelemetry
 
-When manually initializing OpenTelemetry you have to add `SentrySpanProcessor` and `SentryPropagator` to your configuration.
+Our `sentry-opentelemetry-agentless` dependency also adds `opentelemetry-sdk-extension-autoconfigure` which takes care of configuring OpenTelemetry to work with Sentry. There's two ways to trigger it.
 
-```java {tabTitle: Java}
-import io.opentelemetry.api.OpenTelemetry;
-import io.opentelemetry.context.propagation.ContextPropagators;
-import io.opentelemetry.sdk.OpenTelemetrySdk;
-import io.opentelemetry.sdk.trace.SdkTracerProvider;
-
-import io.sentry.opentelemetry.SentryPropagator;
-import io.sentry.opentelemetry.SentrySpanProcessor;
+1. Using a property on startup
 
+Add `-Dotel.java.global-autoconfigure.enabled=true` to the `java` command when starting your application.
 
-SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
-    .addSpanProcessor(new SentrySpanProcessor())
-    .build();
+2. Using `AutoConfiguredOpenTelemetrySdk`
 
-OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
-    .setTracerProvider(sdkTracerProvider)
-    .setPropagators(ContextPropagators.create(new SentryPropagator()))
-    .buildAndRegisterGlobal();
+```java {tabTitle: Java}
+import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;
+
+AutoConfiguredOpenTelemetrySdk.builder()
+  .setResultAsGlobal()
+  .addPropertiesSupplier(() -> {
+    final Map<String, String> properties = new HashMap<>();
+    properties.put("otel.logs.exporter", "none");
+    properties.put("otel.metrics.exporter", "none");
+    properties.put("otel.traces.exporter", "none");
+    return properties;
+  })
+  .build();
 ```
 
 ```kotlin {tabTitle: Kotlin}
-import io.opentelemetry.api.OpenTelemetry
-import io.opentelemetry.context.propagation.ContextPropagators
-import io.opentelemetry.sdk.OpenTelemetrySdk
-import io.opentelemetry.sdk.trace.SdkTracerProvider
-
-import io.sentry.opentelemetry.SentryPropagator
-import io.sentry.opentelemetry.SentrySpanProcessor
-
-val sdkTracerProvider = SdkTracerProvider.builder()
-    .addSpanProcessor(SentrySpanProcessor())
-    .build()
-
-val openTelemetry = OpenTelemetrySdk.builder()
-    .setTracerProvider(sdkTracerProvider)
-    .setPropagators(ContextPropagators.create(SentryPropagator()))
-    .buildAndRegisterGlobal()
+import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk
+
+AutoConfiguredOpenTelemetrySdk.builder()
+  .setResultAsGlobal()
+  .addPropertiesSupplier{
+    return mapOf(
+      "otel.logs.exporter" to "none",
+      "otel.metrics.exporter" to "none",
+      "otel.traces.exporter" to "none"
+    )
+  }
+  .build()
 ```
 
 #### Initializing Sentry
 
-You have to set the `instrumenter` option to `otel`. This disables all Sentry instrumentation and uses the chosen OpenTelemetry tracers for creating spans.
-
-To ensure errors are properly linked to transactions that were created by the OpenTelemetry integration, add the `OpenTelemetryLinkErrorEventProcessor`:
-
+You can initialize Sentry as usual, fore example, by calling `Sentry.init`:
 
 ```java {tabTitle: Java}
-import io.sentry.Instrumenter;
 import io.sentry.Sentry;
-import io.sentry.opentelemetry.OpenTelemetryLinkErrorEventProcessor;
 
 Sentry.init(options -> {
   options.setDsn("___PUBLIC_DSN___");
   options.setTracesSampleRate(1.0);
-  options.setInstrumenter(Instrumenter.OTEL);
-  options.addEventProcessor(new OpenTelemetryLinkErrorEventProcessor());
 });
 ```
 
 ```kotlin {tabTitle: Kotlin}
-import io.sentry.Instrumenter
 import io.sentry.Sentry
-import io.sentry.opentelemetry.OpenTelemetryLinkErrorEventProcessor
 
 Sentry.init { options ->
   options.dsn = "___PUBLIC_DSN___"
   options.tracesSampleRate = 1.0
-  options.instrumenter = Instrumenter.OTEL
-  options.addEventProcessor(OpenTelemetryLinkErrorEventProcessor())
 }
 ```