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're unsure whether to use the Java Agent, please have a look at what the OpenTelemetry SDK has to say about this.
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-8.0.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-8.0.0.jar -jar your-application.jar
Here's the sentry.properties file that goes with it:
sentry.propertiesdsn=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 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.
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
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.
To turn off log exporting, set OTEL_LOGS_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-8.0.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_AUTO_INIT=false java -javaagent:sentry-opentelemetry-agent-8.0.0.jar -jar your-application.jar
The Spring Boot Sentry SDK will take care of initializing Sentry, just make sure a tracesSampleRate has been set:
sentry.dsn=https://examplePublicKey@o0.ingest.sentry.io/0
sentry.traces-sample-rate=1.0
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 java command.
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.
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
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.
To turn off log exporting, set OTEL_LOGS_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.
In addition to the Sentry Spring Boot SDK, you will need to add sentry-opentelemetry-agentless-spring as a dependency:
implementation 'io.sentry:sentry-opentelemetry-agentless-spring:8.0.0'
You'll have to configure both OpenTelemetry and Sentry to see transactions in Sentry and have errors linked to transactions created by OpenTelemetry.
Our sentry-opentelemetry-agentless-spring dependency also adds opentelemetry-spring-boot-starter which takes care of configuring OpenTelemetry to work with Sentry.
Enable the Sentry propagator for OpenTelemetry by adding the following to your Spring configuration:
sentry.dsn=https://examplePublicKey@o0.ingest.sentry.io/0
sentry.traces-sample-rate=1.0
otel.propagators=sentry
The Sentry Spring Boot SDK will take care of the rest.
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 have the OpenTelemetry SDK in you classpath, you can also instrument your code manually using the OpenTelemetry API as documented in the OpenTelemetry docs.
A manually created span for HTTP requests needs to declare its SpanKind as well as the HttpAttributes.HTTP_REQUEST_METHOD attribute, so that Sentry can correctly process these:
Span span = tracer.spanBuilder("myspan")
.setAttribute(HTTP_REQUEST_METHOD, "GET")
.setSpanKind(SpanKind.SERVER)
.startSpan();
By default OpenTelemetry does not capture any HTTP headers. This, however, can be configured using system properties or environment variables as per OpenTelemetry's configuration documentation here. Each variable is a comma-separated list of HTTP header names that should be captured.
OTEL_INSTRUMENTATION_HTTP_CLIENT_CAPTURE_REQUEST_HEADERSOTEL_INSTRUMENTATION_HTTP_CLIENT_CAPTURE_RESPONSE_HEADERS
OTEL_INSTRUMENTATION_HTTP_SERVER_CAPTURE_REQUEST_HEADERSOTEL_INSTRUMENTATION_HTTP_SERVER_CAPTURE_RESPONSE_HEADERS
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").