diff --git a/src/platform-includes/performance/opentelemetry-install/with-java-agent/with-auto-init/java.mdx b/src/platform-includes/performance/opentelemetry-install/with-java-agent/with-auto-init/java.mdx new file mode 100644 index 0000000000000..563efff6bcaf4 --- /dev/null +++ b/src/platform-includes/performance/opentelemetry-install/with-java-agent/with-auto-init/java.mdx @@ -0,0 +1 @@ +You can download the latest version of the `sentry-opentelemetry-agent-{{ packages.version('sentry.java.opentelemetry-agent') }}.zip` from [GitHub](https://github.com/getsentry/sentry-java/releases/) which contains the `JAR` file used in this docs page. diff --git a/src/platform-includes/performance/opentelemetry-install/with-java-agent/without-auto-init/java.mdx b/src/platform-includes/performance/opentelemetry-install/with-java-agent/without-auto-init/java.mdx new file mode 100644 index 0000000000000..100c6a9186146 --- /dev/null +++ b/src/platform-includes/performance/opentelemetry-install/with-java-agent/without-auto-init/java.mdx @@ -0,0 +1,7 @@ +You can download the latest version of the `sentry-opentelemetry-agent-{{ packages.version('sentry.java.opentelemetry-agent') }}.zip` from [GitHub](https://github.com/getsentry/sentry-java/releases/) which contains the `JAR` file used in this docs page. + +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:{{ packages.version('sentry.java.opentelemetry-core', '6.9.2') }}' +``` diff --git a/src/platform-includes/performance/opentelemetry-install/without-java-agent/java.mdx b/src/platform-includes/performance/opentelemetry-install/without-java-agent/java.mdx new file mode 100644 index 0000000000000..b5046d319ebb3 --- /dev/null +++ b/src/platform-includes/performance/opentelemetry-install/without-java-agent/java.mdx @@ -0,0 +1,5 @@ +In addition to OpenTelemetry dependencies and your typical Sentry dependencies, you will need to add `sentry-opentelemetry-core` as a dependency: + +```groovy {tabTitle:Gradle} +implementation 'io.sentry:sentry-opentelemetry-core:{{ packages.version('sentry.java.opentelemetry-core', '6.9.2') }}' +``` diff --git a/src/platform-includes/performance/opentelemetry-setup/with-java-agent/exporter-messages/java.mdx b/src/platform-includes/performance/opentelemetry-setup/with-java-agent/exporter-messages/java.mdx new file mode 100644 index 0000000000000..b775f44e6fd03 --- /dev/null +++ b/src/platform-includes/performance/opentelemetry-setup/with-java-agent/exporter-messages/java.mdx @@ -0,0 +1,17 @@ +If you're using `sentry-opentelemetry-agent` but don't need to use OpenTelemetry exporters, add +the following environment variables to turn off exporters and stop receiving error messages about +servers not being reachable in the logs. + +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 +``` + +#### Traces + +To turn off traces exporting, set `OTEL_TRACES_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). + +#### 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). diff --git a/src/platform-includes/performance/opentelemetry-setup/with-java-agent/with-auto-init/debugging/java.mdx b/src/platform-includes/performance/opentelemetry-setup/with-java-agent/with-auto-init/debugging/java.mdx new file mode 100644 index 0000000000000..049fab21a4177 --- /dev/null +++ b/src/platform-includes/performance/opentelemetry-setup/with-java-agent/with-auto-init/debugging/java.mdx @@ -0,0 +1,4 @@ +To enable debug logging in Sentry, set `SENTRY_DEBUG=true` as an environment variable or +add `debug=true` to your `sentry.properties`. + +To show debug output for OpenTelemetry, add `-Dotel.javaagent.debug=true` to the `java` command. diff --git a/src/platform-includes/performance/opentelemetry-setup/with-java-agent/with-auto-init/java.mdx b/src/platform-includes/performance/opentelemetry-setup/with-java-agent/with-auto-init/java.mdx new file mode 100644 index 0000000000000..bb8fbf48bf616 --- /dev/null +++ b/src/platform-includes/performance/opentelemetry-setup/with-java-agent/with-auto-init/java.mdx @@ -0,0 +1,12 @@ +This `java` command shows how to run your application using `sentry-opentelemetry-agent`: + +```bash +SENTRY_PROPERTIES_FILE=sentry.properties java -javaagent:sentry-opentelemetry-agent-{{ packages.version('sentry.java.opentelemetry-agent') }}.jar -jar your-application.jar +``` + +Here's the `sentry.properties` file that goes with it: + +```properties {filename:sentry.properties} +dsn=___DSN___ +traces-sample-rate=1.0 +``` diff --git a/src/platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/debugging/java.mdx b/src/platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/debugging/java.mdx new file mode 100644 index 0000000000000..049fab21a4177 --- /dev/null +++ b/src/platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/debugging/java.mdx @@ -0,0 +1,4 @@ +To enable debug logging in Sentry, set `SENTRY_DEBUG=true` as an environment variable or +add `debug=true` to your `sentry.properties`. + +To show debug output for OpenTelemetry, add `-Dotel.javaagent.debug=true` to the `java` command. diff --git a/src/platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/debugging/java.spring-boot.mdx b/src/platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/debugging/java.spring-boot.mdx new file mode 100644 index 0000000000000..f38646dfced84 --- /dev/null +++ b/src/platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/debugging/java.spring-boot.mdx @@ -0,0 +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. diff --git a/src/platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/java.mdx b/src/platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/java.mdx new file mode 100644 index 0000000000000..ee9f1e402d737 --- /dev/null +++ b/src/platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/java.mdx @@ -0,0 +1,14 @@ +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`: + +```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()); +}); +``` diff --git a/src/platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/java.spring-boot.mdx b/src/platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/java.spring-boot.mdx new file mode 100644 index 0000000000000..ca94eb7863d64 --- /dev/null +++ b/src/platform-includes/performance/opentelemetry-setup/with-java-agent/without-auto-init/java.spring-boot.mdx @@ -0,0 +1,11 @@ +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: + +```properties {filename:application.properties} +sentry.dsn=___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 +``` diff --git a/src/platform-includes/performance/opentelemetry-setup/without-java-agent/java.mdx b/src/platform-includes/performance/opentelemetry-setup/without-java-agent/java.mdx new file mode 100644 index 0000000000000..e1273a068ef69 --- /dev/null +++ b/src/platform-includes/performance/opentelemetry-setup/without-java-agent/java.mdx @@ -0,0 +1,42 @@ +#### Initializing OpenTelemetry + +When manually initializing OpenTelemetry you have to add `SentrySpanProcessor` and `SentryPropagator` to your configuration. + +```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; + + +SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder() + .addSpanProcessor(new SentrySpanProcessor()) + .build(); + +OpenTelemetry openTelemetry = OpenTelemetrySdk.builder() + .setTracerProvider(sdkTracerProvider) + .setPropagators(ContextPropagators.create(new 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. + +To ensure errors are properly linked to transactions that were created by the OpenTelemetry integration, add the `OpenTelemetryLinkErrorEventProcessor`: + +```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()); +}); +``` diff --git a/src/platform-includes/performance/opentelemetry-setup/without-java-agent/java.spring-boot.mdx b/src/platform-includes/performance/opentelemetry-setup/without-java-agent/java.spring-boot.mdx new file mode 100644 index 0000000000000..a7f11c222f91d --- /dev/null +++ b/src/platform-includes/performance/opentelemetry-setup/without-java-agent/java.spring-boot.mdx @@ -0,0 +1,56 @@ +#### Initializing OpenTelemetry + +When manually initializing OpenTelemetry you have to add `SentrySpanProcessor` and `SentryPropagator` to your configuration. + +```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; + + +SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder() + .addSpanProcessor(new SentrySpanProcessor()) + .build(); + +OpenTelemetry openTelemetry = OpenTelemetrySdk.builder() + .setTracerProvider(sdkTracerProvider) + .setPropagators(ContextPropagators.create(new 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} +sentry.dsn=___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 +``` + +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(); + } +} +``` diff --git a/src/platforms/java/common/performance/instrumentation/opentelemetry.mdx b/src/platforms/java/common/performance/instrumentation/opentelemetry.mdx new file mode 100644 index 0000000000000..be12cd71804ef --- /dev/null +++ b/src/platforms/java/common/performance/instrumentation/opentelemetry.mdx @@ -0,0 +1,63 @@ +--- +title: OpenTelemetry Support +sidebar_order: 20 +description: "Using OpenTelemetry with Sentry Performance." +--- + + + +There are multiple ways of configuring your [OpenTelemetry SDK](https://opentelemetry.io/) to send traces and spans to Sentry. + +## 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. Only your `DSN` and `tracesSampleRate` need to be configured. + +### Install + + + +### Usage + + + +### Debugging + + + +### Turn Off Exporter Error Messages + + + +## Using `sentry-opentelemetry-agent` Without Auto Initialization + +You may also disable automatic initialization of Sentry in `sentry-opentelemetry-agent` by setting `SENTRY_AUTO_INIT=false` as environment variable. This means you will either have to use another Sentry integration that performs initialization, for example Spring Boot, or initialize Sentry manually. + +### Install + + + +### Usage + + + +### Debugging + + + +### Turn Off Exporter Error Messages + + + +## Using OpenTelemetry Without Any Java Agent + +If the Java Agent approach is not for you, you may also manually initialize OpenTelemetry. We have a separate dependency for this use case that allows you to reuse classes used by `sentry-opentelemetry-agent`. + +### Install + + + +### Usage + +You will have to configure both OpenTelemetry and Sentry to see transactions in Sentry and have errors linked to transactions created by OpenTelemetry. + +