Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update OpenTelemetry dosc for Java v8 #12209

Open
wants to merge 1 commit into
base: feat/java-v8-changes
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down Expand Up @@ -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

Expand Down
12 changes: 1 addition & 11 deletions docs/platforms/java/migration/7.x-to-8.0.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
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).
Original file line number Diff line number Diff line change
@@ -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') }}'
```
Original file line number Diff line number Diff line change
@@ -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>.
Original file line number Diff line number Diff line change
@@ -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>
```
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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
Expand All @@ -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).
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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())
}
```
Original file line number Diff line number Diff line change
@@ -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
```
Original file line number Diff line number Diff line change
@@ -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, e.g. by calling `Sentry.init`:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can initialize Sentry as usual, e.g. by calling `Sentry.init`:
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())
}
```
Original file line number Diff line number Diff line change
@@ -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<String>) {
SpringApplication.run(SentryDemoApplication.class, args);
}

@Bean
fun otelLinkEventProcessor(): OpenTelemetryLinkErrorEventProcessor {
return OpenTelemetryLinkErrorEventProcessor()
}
}
```
The Sentry Spring Boot SDK will take care of the rest.
Loading