diff --git a/docs/platforms/java/common/tracing/instrumentation/opentelemetry.mdx b/docs/platforms/java/common/tracing/instrumentation/opentelemetry.mdx index 74626109e6856..e40f162abc735 100644 --- a/docs/platforms/java/common/tracing/instrumentation/opentelemetry.mdx +++ b/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. + +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/). + + ## 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 diff --git a/docs/platforms/java/migration/7.x-to-8.0.mdx b/docs/platforms/java/migration/7.x-to-8.0.mdx index b478588c40c51..2ff214329bece 100644 --- a/docs/platforms/java/migration/7.x-to-8.0.mdx +++ b/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). diff --git a/platform-includes/performance/opentelemetry-install/with-java-agent/without-auto-init/java.mdx b/platform-includes/performance/opentelemetry-install/with-java-agent/without-auto-init/java.mdx index 9178a8af65a6f..ac2516e257209 100644 --- a/platform-includes/performance/opentelemetry-install/with-java-agent/without-auto-init/java.mdx +++ b/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') }}' -``` diff --git a/platform-includes/performance/opentelemetry-install/without-java-agent/java.mdx b/platform-includes/performance/opentelemetry-install/without-java-agent/java.mdx index 8b2c51fb3c9ee..5954b189095bc 100644 --- a/platform-includes/performance/opentelemetry-install/without-java-agent/java.mdx +++ b/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} + + io.sentry + sentry-opentelemetry-agentless + {{@inject packages.version('sentry.java.opentelemetry-agentless', '8.0.0') }} + +``` + +Please note, if you're using Spring Boot, there's a separate `sentry-opentelemetry-agentless-spring` dependency. You can find out more here. diff --git a/platform-includes/performance/opentelemetry-install/without-java-agent/java.spring-boot.mdx b/platform-includes/performance/opentelemetry-install/without-java-agent/java.spring-boot.mdx new file mode 100644 index 0000000000000..55282a31cce26 --- /dev/null +++ b/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} + + io.sentry + sentry-opentelemetry-agentless-spring + {{@inject packages.version('sentry.java.opentelemetry-agentless-spring', '8.0.0') }} + +``` diff --git a/platform-includes/performance/opentelemetry-setup/with-java-agent/exporter-messages/java.mdx b/platform-includes/performance/opentelemetry-setup/with-java-agent/exporter-messages/java.mdx index 755e70ffc10c9..cb3f96cfc2f56 100644 --- a/platform-includes/performance/opentelemetry-setup/with-java-agent/exporter-messages/java.mdx +++ b/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). diff --git a/platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/debugging/java.spring-boot.mdx b/platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/debugging/java.spring-boot.mdx index f38646dfced84..ea437a41bdf6c 100644 --- a/platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/debugging/java.spring-boot.mdx +++ b/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. diff --git a/platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/java.mdx b/platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/java.mdx index c0c0df2bac2b8..b3477d5b9c60b 100644 --- a/platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/java.mdx +++ b/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()) } ``` diff --git a/platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/java.spring-boot.mdx b/platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/java.spring-boot.mdx index 94ac00f3f0b68..03cd5d7664154 100644 --- a/platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/java.spring-boot.mdx +++ b/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 ``` diff --git a/platform-includes/performance/opentelemetry-setup/without-java-agent/java.mdx b/platform-includes/performance/opentelemetry-setup/without-java-agent/java.mdx index 6b2874c6a1aba..3ff6f05c012f8 100644 --- a/platform-includes/performance/opentelemetry-setup/without-java-agent/java.mdx +++ b/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 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, e.g. 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()) } ``` diff --git a/platform-includes/performance/opentelemetry-setup/without-java-agent/java.spring-boot.mdx b/platform-includes/performance/opentelemetry-setup/without-java-agent/java.spring-boot.mdx index b1f48756e5590..ad703acc4f109 100644 --- a/platform-includes/performance/opentelemetry-setup/without-java-agent/java.spring-boot.mdx +++ b/platform-includes/performance/opentelemetry-setup/without-java-agent/java.spring-boot.mdx @@ -1,92 +1,23 @@ #### Initializing OpenTelemetry -When manually initializing OpenTelemetry you have to add `SentrySpanProcessor` and `SentryPropagator` to your configuration. +Our `sentry-opentelemetry-agentless-spring` dependency also adds `opentelemetry-spring-boot-starter` which takes care of configuring OpenTelemetry to work with Sentry. -```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; +Enable the Sentry propagator for OpenTelemetry by adding the following to your Spring configuration: - -SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder() - .addSpanProcessor(new SentrySpanProcessor()) - .build(); - -OpenTelemetry openTelemetry = OpenTelemetrySdk.builder() - .setTracerProvider(sdkTracerProvider) - .setPropagators(ContextPropagators.create(new SentryPropagator())) - .buildAndRegisterGlobal(); -``` - -```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() -``` - -#### 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 instead. - - -```properties {filename:application.properties} +```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 +otel.propagators=sentry ``` -You also have to manually provide the `OpenTelemetryLinkErrorEventProcessor` bean to ensure errors are properly linked to transactions that were created by the OpenTelemetry integration: - -```java {filename:SentryDemoApplication.java} -import io.sentry.opentelemetry.OpenTelemetryLinkErrorEventProcessor; - -@SpringBootApplication -public class SentryDemoApplication { - public static void main(String[] args) { - SpringApplication.run(SentryDemoApplication.class, args); - } - - ... - - @Bean - OpenTelemetryLinkErrorEventProcessor otelLinkEventProcessor() { - return new OpenTelemetryLinkErrorEventProcessor(); - } -} +```yaml {tabTitle: application.yml} +sentry: + dsn: ___PUBLIC_DSN___ + traces-sample-rate: 1.0 +otel: + propagators: + - sentry ``` -```kotlin {filename:SentryDemoApplication.kt} -import io.sentry.opentelemetry.OpenTelemetryLinkErrorEventProcessor - -@SpringBootApplication -public class SentryDemoApplication { - fun main(args: Array) { - SpringApplication.run(SentryDemoApplication.class, args); - } - - @Bean - fun otelLinkEventProcessor(): OpenTelemetryLinkErrorEventProcessor { - return OpenTelemetryLinkErrorEventProcessor() - } -} -``` +The Sentry Spring Boot SDK will take care of the rest.