OpenTelemetry Support
Using OpenTelemetry with Sentry Performance.
There are multiple ways to configure your OpenTelemetry SDK and send traces and spans to Sentry. They're described below.
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
.
You can download the latest version of the sentry-opentelemetry-agent-7.9.0.jar
from MavenCentral. It's also available as a ZIP
containing the JAR
used on this page on GitHub.
This java
command shows how to run your application using sentry-opentelemetry-agent
:
SENTRY_PROPERTIES_FILE=sentry.properties java -javaagent:sentry-opentelemetry-agent-7.9.0.jar -jar your-application.jar
Here's the sentry.properties
file that goes with it:
sentry.properties
dsn=https://examplePublicKey@o0.ingest.sentry.io/0
traces-sample-rate=1.0
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.
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
To turn off traces exporting, set OTEL_TRACES_EXPORTER=none
as an environment variable per OpenTelemetry GitHub.
To turn off metrics exporting, set OTEL_METRICS_EXPORTER=none
as an environment variable per OpenTelemetry GitHub.
You may also disable automatic initialization of Sentry in sentry-opentelemetry-agent
by setting SENTRY_AUTO_INIT=false
as an environment variable. Doing this will mean you'll either have to use another Sentry integration that performs initialization, (for example Spring Boot), or initialize Sentry manually.
You can download the latest version of the sentry-opentelemetry-agent-7.9.0.jar
from MavenCentral. It's also available as a ZIP
containing the JAR
used on this page on GitHub.
To ensure errors are properly linked to transactions that were created by the OpenTelemetry integration, you need an additional dependency:
implementation 'io.sentry:sentry-opentelemetry-core:7.9.0'
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
:
import io.sentry.Instrumenter;
import io.sentry.Sentry;
import io.sentry.opentelemetry.OpenTelemetryLinkErrorEventProcessor;
Sentry.init(options -> {
options.setDsn("https://examplePublicKey@o0.ingest.sentry.io/0");
options.setTracesSampleRate(1.0);
options.setInstrumenter(Instrumenter.OTEL);
options.addEventProcessor(new OpenTelemetryLinkErrorEventProcessor());
});
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.
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
To turn off traces exporting, set OTEL_TRACES_EXPORTER=none
as an environment variable per OpenTelemetry GitHub.
To turn off metrics exporting, set OTEL_METRICS_EXPORTER=none
as an environment variable per OpenTelemetry GitHub.
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
.
In addition to OpenTelemetry dependencies and your typical Sentry dependencies, you will need to add sentry-opentelemetry-core
as a dependency:
implementation 'io.sentry:sentry-opentelemetry-core:7.9.0'
You'll have to configure both OpenTelemetry and Sentry to see transactions in Sentry and have errors linked to transactions created by OpenTelemetry.
When manually initializing OpenTelemetry you have to add SentrySpanProcessor
and SentryPropagator
to your configuration.
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();
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
:
import io.sentry.Instrumenter;
import io.sentry.Sentry;
import io.sentry.opentelemetry.OpenTelemetryLinkErrorEventProcessor;
Sentry.init(options -> {
options.setDsn("https://examplePublicKey@o0.ingest.sentry.io/0");
options.setTracesSampleRate(1.0);
options.setInstrumenter(Instrumenter.OTEL);
options.addEventProcessor(new OpenTelemetryLinkErrorEventProcessor());
});
With Sentry’s OpenTelemetry SDK, an OpenTelemetry Span
becomes a Sentry Transaction
or Span
. The first Span
sent through the Sentry SpanProcessor
is a Transaction
, and any child Span
gets attached to the first Transaction
upon checking the parent Span
context. This is true for the OpenTelemetry root Span
and any top level Span
in the system. For example, a request sent from frontend to backend will create an OpenTelemetry root Span
with a corresponding Sentry Transaction
. The backend request will create a new Sentry Transaction
for the OpenTelemetry Span
. The Sentry Transaction
and Span
are linked as a trace for navigation and error tracking purposes.
If you need more fine grained control over Sentry, take a look at the Configuration page. In case you'd like to filter out transactions before sending them to Sentry (to get rid of health checks, for example), you may find the Filtering page helpful.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").