Improve Java OpenTelemetry docs (#13202)

adinauer · lbloder · bitsandfoxes · commit 8fbca7d8c230 · 2025-04-24T17:10:36.000+02:00
* Improve Java OpenTelemetry docs

* try to fix lint

* try to fix lint2

* Apply suggestions from code review

Co-authored-by: Lukas Bloder &lt;lukas.bloder@gmail.com&gt;

* PR feedback

---------

Co-authored-by: Lukas Bloder &lt;lukas.bloder@gmail.com&gt;
diff --git a/docs/platforms/java/common/migration/7.x-to-8.0.mdx b/docs/platforms/java/common/migration/7.x-to-8.0.mdx
@@ -109,7 +109,7 @@ If you've been using the previous version of `sentry-opentelemetry-agent`, simpl
 If you've not been using the Sentry OpenTelemetry agent before, you can add `sentry-opentelemetry-agent` to your setup by downloading the latest release and using it when starting up your application
 - `SENTRY_PROPERTIES_FILE=sentry.properties java -javaagent:sentry-opentelemetry-agent-x.x.x.jar -jar your-application.jar`
 - 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.
+- You may find the <PlatformLink to="/opentelemetry/setup/agent/auto-init/">docs page</PlatformLink> 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 use `Sentry.init` as usual.
 
diff --git a/docs/platforms/java/common/opentelemetry/index.mdx b/docs/platforms/java/common/opentelemetry/index.mdx
@@ -0,0 +1,21 @@
+---
+title: OpenTelemetry Support
+sdk: sentry.java.opentelemetry-agent
+description: "Using OpenTelemetry with Sentry."
+sidebar_order: 160
+---
+
+[OpenTelemetry](https://opentelemetry.io/) enhances Sentry by providing support for more frameworks and libraries that:
+
+- Let you create more spans, for example around requests.
+- Provide `Context` propagation that also takes care of propagating Sentry `Scopes`, ensuring things like tags and other information end up on the correct event.
+- Extract tracing information from incoming requests and consumed messages.
+- Inject tracing information into outgoing requests and produced messages.
+
+Please take a look at the [OpenTelemetry GitHub repository](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation) for a full list of available instrumentations.
+
+In some cases there is instrumentation available by both OpenTelemetry and Sentry. In this case we automatically configure the Sentry instrumentation to not create spans and instead let OpenTelemetry take over.
+
+You may use OpenTelemetry API or Sentry API to manually instrument your application. Both will end up in Sentry. If you are already using Sentry API, you can keep using it when switching over to our OpenTelemetry integration. If you already have OpenTelemetry instrumentation in place you can have the resulting spans sent to Sentry.
+
+<PageGrid />
diff --git a/docs/platforms/java/common/opentelemetry/setup/agent/auto-init.mdx b/docs/platforms/java/common/opentelemetry/setup/agent/auto-init.mdx
@@ -0,0 +1,26 @@
+---
+title: OpenTelemetry Agent With Auto Init
+sdk: sentry.java.opentelemetry-agent
+description: "Using OpenTelemetry with sentry-opentelemetry-agent and AUTO_INIT enabled."
+sidebar_order: 100
+---
+
+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`.
+
+<PlatformContent includePath="performance/opentelemetry-setup/agent-auto-init-recommendation/enabled" />
+
+## Install
+
+<PlatformContent includePath="performance/opentelemetry-install/with-java-agent/with-auto-init" />
+
+## Usage
+
+<PlatformContent includePath="performance/opentelemetry-setup/with-java-agent/with-auto-init" />
+
+## Debugging
+
+<PlatformContent includePath="performance/opentelemetry-setup/with-java-agent/with-auto-init/debugging" />
+
+## Turn Off Exporter Error Messages
+
+<PlatformContent includePath="performance/opentelemetry-setup/with-java-agent/exporter-messages" />
diff --git a/docs/platforms/java/common/opentelemetry/setup/agent/index.mdx b/docs/platforms/java/common/opentelemetry/setup/agent/index.mdx
@@ -0,0 +1,16 @@
+---
+title: OpenTelemetry Agent
+sdk: sentry.java.opentelemetry-agent
+description: "Using OpenTelemetry with sentry-opentelemetry-agent."
+sidebar_order: 100
+---
+
+<PlatformContent includePath="performance/opentelemetry-setup/agent-explanation" />
+
+When using `sentry-opentelemetry-agent` you can choose whether the Agent should call `Sentry.init`.
+By default the Agent will initialize Sentry for you. If you prefer to manually initialize Sentry or have another integration perform the init you can disable this behaviour.
+
+<PlatformContent includePath="performance/opentelemetry-setup/agent-auto-init-recommendation/enabled" />
+<PlatformContent includePath="performance/opentelemetry-setup/agent-auto-init-recommendation/disabled" />
+
+<PageGrid />
diff --git a/docs/platforms/java/common/opentelemetry/setup/agent/no-auto-init.mdx b/docs/platforms/java/common/opentelemetry/setup/agent/no-auto-init.mdx
@@ -0,0 +1,26 @@
+---
+title: OpenTelemetry Agent Without Auto Init
+sdk: sentry.java.opentelemetry-agent
+description: "Using OpenTelemetry with sentry-opentelemetry-agent and AUTO_INIT disabled."
+sidebar_order: 200
+---
+
+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.
+
+<PlatformContent includePath="performance/opentelemetry-setup/agent-auto-init-recommendation/disabled" />
+
+## Install
+
+<PlatformContent includePath="performance/opentelemetry-install/with-java-agent/without-auto-init" />
+
+## Usage
+
+<PlatformContent includePath="performance/opentelemetry-setup/with-java-agent/without-auto-init" />
+
+## Debugging
+
+<PlatformContent includePath="performance/opentelemetry-setup/with-java-agent/without-auto-init/debugging" />
+
+## Turn Off Exporter Error Messages
+
+<PlatformContent includePath="performance/opentelemetry-setup/with-java-agent/exporter-messages" />
diff --git a/docs/platforms/java/common/opentelemetry/setup/agentless.mdx b/docs/platforms/java/common/opentelemetry/setup/agentless.mdx
@@ -0,0 +1,18 @@
+---
+title: OpenTelemetry Agentless
+sdk: sentry.java.opentelemetry-agentless
+description: "Using OpenTelemetry with  sentry-opentelemetry-agentless."
+sidebar_order: 200
+---
+
+If you do not want to use our recommended <PlatformLink to="/opentelemetry/setup/agent">Java Agent</PlatformLink>, we also offer a dependency that allows you to use OpenTelemetry with Sentry.
+
+## Install
+
+<PlatformContent includePath="performance/opentelemetry-install/without-java-agent" />
+
+## Usage
+
+You'll have to configure both OpenTelemetry and Sentry to see transactions in Sentry and have errors linked to transactions created by OpenTelemetry.
+
+<PlatformContent includePath="performance/opentelemetry-setup/without-java-agent" />
diff --git a/docs/platforms/java/common/opentelemetry/setup/index.mdx b/docs/platforms/java/common/opentelemetry/setup/index.mdx
@@ -0,0 +1,20 @@
+---
+title: OpenTelemetry Setup
+sdk: sentry.java.opentelemetry-agent
+description: "Setting up Sentry with OpenTelemetry."
+sidebar_order: 160
+---
+
+There are multiple ways to configure our OpenTelemetry integration. You may chose between using our Java Agent or using one of our agentless dependencies.
+
+## Java Agent
+
+<PlatformContent includePath="performance/opentelemetry-setup/agent-explanation" />
+
+For a guide on how to set up `sentry-opentelemetry-agent`, please have a look at <PlatformLink to="/opentelemetry/setup/agent">the detailed Agent docs</PlatformLink>.
+
+## Agentless
+
+<PlatformContent includePath="performance/opentelemetry-setup/agentless-explanation" />
+
+For a guide on how to set up agentless, please have a look at <PlatformLink to="/opentelemetry/setup/agentless">the detailed Agentless docs</PlatformLink>.
diff --git a/docs/platforms/java/common/opentelemetry/usage/index.mdx b/docs/platforms/java/common/opentelemetry/usage/index.mdx
@@ -0,0 +1,53 @@
+---
+title: OpenTelemetry Usage
+sdk: sentry.java.opentelemetry-agent
+description: "Using OpenTelemetry with Sentry."
+sidebar_order: 160
+---
+
+## OpenTelemetry and Sentry
+
+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.
+
+### Manual Instrumentation with OpenTelemetry
+
+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](https://opentelemetry.io/docs/languages/java/api/#span).
+
+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:
+
+```java {tabTitle:Java}
+Span span = tracer.spanBuilder("myspan")
+  .setAttribute(HTTP_REQUEST_METHOD, "GET")
+  .setSpanKind(SpanKind.SERVER)
+  .startSpan();
+```
+```kotlin {tabTitle:Kotlin}
+val span = tracer.spanBuilder("myspan")
+  .setAttribute(HTTP_REQUEST_METHOD, "GET")
+  .setSpanKind(SpanKind.SERVER)
+  .startSpan()
+```
+
+### Capturing HTTP Headers
+
+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](https://opentelemetry.io/docs/zero-code/java/agent/instrumentation/http/#capturing-http-request-and-response-headers). Each variable is a comma-separated list of HTTP header names that should be captured.
+
+<Alert title="✨ Note">
+
+Please only enable headers you actually want to send to Sentry. Some may contain sensitive data like PII, cookies or tokens.
+
+</Alert>
+
+#### Client variables
+
+- `OTEL_INSTRUMENTATION_HTTP_CLIENT_CAPTURE_REQUEST_HEADERS`
+- `OTEL_INSTRUMENTATION_HTTP_CLIENT_CAPTURE_RESPONSE_HEADERS`
+
+#### Server variables
+
+- `OTEL_INSTRUMENTATION_HTTP_SERVER_CAPTURE_REQUEST_HEADERS`
+- `OTEL_INSTRUMENTATION_HTTP_SERVER_CAPTURE_RESPONSE_HEADERS`
+
+## Additional Configuration
+
+If you need more fine grained control over Sentry, take a look at the <PlatformLink to="/configuration/">Configuration page</PlatformLink>. 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 <PlatformLink to="/configuration/filtering/#filtering-transaction-events">Filtering page</PlatformLink> helpful.
diff --git a/docs/platforms/java/common/tracing/instrumentation/opentelemetry.mdx b/docs/platforms/java/common/tracing/instrumentation/opentelemetry.mdx
@@ -5,103 +5,4 @@ description: "Using OpenTelemetry with Sentry Performance."
 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`.
-
-### Install
-
-<PlatformContent includePath="performance/opentelemetry-install/with-java-agent/with-auto-init" />
-
-### Usage
-
-<PlatformContent includePath="performance/opentelemetry-setup/with-java-agent/with-auto-init" />
-
-### Debugging
-
-<PlatformContent includePath="performance/opentelemetry-setup/with-java-agent/with-auto-init/debugging" />
-
-### Turn Off Exporter Error Messages
-
-<PlatformContent includePath="performance/opentelemetry-setup/with-java-agent/exporter-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 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.
-
-### Install
-
-<PlatformContent includePath="performance/opentelemetry-install/with-java-agent/without-auto-init" />
-
-### Usage
-
-<PlatformContent includePath="performance/opentelemetry-setup/with-java-agent/without-auto-init" />
-
-### Debugging
-
-<PlatformContent includePath="performance/opentelemetry-setup/with-java-agent/without-auto-init/debugging" />
-
-### Turn Off Exporter Error Messages
-
-<PlatformContent includePath="performance/opentelemetry-setup/with-java-agent/exporter-messages" />
-
-## 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.
-
-### Install
-
-<PlatformContent includePath="performance/opentelemetry-install/without-java-agent" />
-
-### Usage
-
-You'll have to configure both OpenTelemetry and Sentry to see transactions in Sentry and have errors linked to transactions created by OpenTelemetry.
-
-<PlatformContent includePath="performance/opentelemetry-setup/without-java-agent" />
-
-## OpenTelemetry and Sentry
-
-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.
-
-### Manual Instrumentation with OpenTelemetry
-
-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](https://opentelemetry.io/docs/languages/java/api/#span).
-
-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:
-
-```java {tabTitle:Java}
-Span span = tracer.spanBuilder("myspan")
-  .setAttribute(HTTP_REQUEST_METHOD, "GET")
-  .setSpanKind(SpanKind.SERVER)
-  .startSpan();
-```
-```kotlin {tabTitle:Kotlin}
-val span = tracer.spanBuilder("myspan")
-  .setAttribute(HTTP_REQUEST_METHOD, "GET")
-  .setSpanKind(SpanKind.SERVER)
-  .startSpan()
-```
-
-### Capturing HTTP Headers
-
-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](https://opentelemetry.io/docs/zero-code/java/agent/instrumentation/http/#capturing-http-request-and-response-headers). Each variable is a comma-separated list of HTTP header names that should be captured.
-
-#### Client variables
-
-- `OTEL_INSTRUMENTATION_HTTP_CLIENT_CAPTURE_REQUEST_HEADERS`
-- `OTEL_INSTRUMENTATION_HTTP_CLIENT_CAPTURE_RESPONSE_HEADERS`
-
-#### Server variables
-
-- `OTEL_INSTRUMENTATION_HTTP_SERVER_CAPTURE_REQUEST_HEADERS`
-- `OTEL_INSTRUMENTATION_HTTP_SERVER_CAPTURE_RESPONSE_HEADERS`
-
-## Additional Configuration
-
-If you need more fine grained control over Sentry, take a look at the <PlatformLink to="/configuration/">Configuration page</PlatformLink>. 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 <PlatformLink to="/configuration/filtering/#filtering-transaction-events">Filtering page</PlatformLink> helpful.
+This page has moved to <PlatformLink to="/opentelemetry">a top level page</PlatformLink>.
diff --git a/platform-includes/performance/opentelemetry-install/without-java-agent/java.mdx b/platform-includes/performance/opentelemetry-install/without-java-agent/java.mdx
@@ -11,4 +11,4 @@ implementation 'io.sentry:sentry-opentelemetry-agentless:{{@inject packages.vers
 </dependency>
 ```
 
-Please note, if you're using Spring Boot, there's a separate `sentry-opentelemetry-agentless-spring` dependency. You can [find out more here](/platforms/java/guides/spring-boot/tracing/instrumentation/opentelemetry/).
+Please note, if you're using Spring Boot, there's a separate `sentry-opentelemetry-agentless-spring` dependency. You can [find out more here](/platforms/java/guides/spring-boot/opentelemetry/setup/agentless/).
diff --git a/platform-includes/performance/opentelemetry-setup/agent-auto-init-recommendation/disabled/java.mdx b/platform-includes/performance/opentelemetry-setup/agent-auto-init-recommendation/disabled/java.mdx
@@ -0,0 +1,3 @@
+<PlatformSection supported={["java.spring", "java.spring-boot"]}>
+For Spring Boot we recommend disabling the Agents `AUTO_INIT` and instead letting our Spring Boot integration take care of initializing the SDK as this allows for a more convenient configuration of Sentry using `application.properties`/`application.yml` and Spring beans.
+</PlatformSection>
diff --git a/platform-includes/performance/opentelemetry-setup/agent-auto-init-recommendation/enabled/java.mdx b/platform-includes/performance/opentelemetry-setup/agent-auto-init-recommendation/enabled/java.mdx
@@ -0,0 +1,3 @@
+<PlatformSection notSupported={["java.spring", "java.spring-boot"]}>
+We recommend letting the Java Agent take care of initializing Sentry as this way the SDK will be ready early in your applications lifecycle.
+</PlatformSection>
diff --git a/platform-includes/performance/opentelemetry-setup/agent-explanation/java.mdx b/platform-includes/performance/opentelemetry-setup/agent-explanation/java.mdx
@@ -0,0 +1,24 @@
+This is our recommended way of setting up Sentry with OpenTelemetry as it offers the broadest support for frameworks and libraries.
+
+The `sentry-opentelemetry-agent` makes use of the [`java` command's `-javaagent` argument](https://docs.oracle.com/en/java/javase/17/docs/api/java.instrument/java/lang/instrument/package-summary.html). This Java Agent will run some code before starting your application, configuring OpenTelemetry and Sentry and also dynamically injects bytecode into your application.
+
+The injected code allows OpenTelemetry and by extension also Sentry to:
+
+- Instrument your application by creating spans around things like HTTP requests, database queries, and many more.
+- Propagate OpenTelemetry `Context` and Sentry `Scopes` through libraries
+- Extract tracing information from incoming requests and consumed messages
+- Inject tracing information into outgoing requests and produced messages
+
+The `sentry-opentelemetry-agent` is packaged as a JAR file and is separate from your applications JAR / WAR file. This means you will have to manage the version on your server and upgrade it whenever you upgrade the Sentry SDK dependency in your application should you have it.
+
+<Alert title="✨ Note">
+
+Sentry Java SDK dependencies as well as `sentry-opentelemetry-agent` version must always be aligned. Mixing them is very likely to cause crashes and as of version `8.6.0` the Java SDK will throw an exception on `init` in this case to help catch the issue during development.
+
+</Alert>
+
+<PlatformSection supported={["java.spring", "java.spring-boot"]} notSupported={["java"]}>
+If you're unsure whether to use the Java Agent, please have a look at [OpenTelemetry documentation](https://opentelemetry.io/docs/zero-code/java/spring-boot-starter/).
+</PlatformSection>
+
+Since `sentry-opentelemetry-agent` is based on `opentelemetry-agent`, you may also find [OpenTelmetry docs](https://opentelemetry.io/docs/zero-code/java/agent/) helpful.
diff --git a/platform-includes/performance/opentelemetry-setup/agentless-explanation/java.mdx b/platform-includes/performance/opentelemetry-setup/agentless-explanation/java.mdx
@@ -0,0 +1,13 @@
+We also offer a way of using Sentry with OpenTelemetry that does not require a Java Agent but instead makes use of a dependency that can be packaged with your application.
+
+<PlatformSection notSupported={["java.spring", "java.spring-boot"]}>
+The `sentry-opentelemetry-agentless` dependency combines all modules and dependencies needed to use Sentry with OpenTelemetry.
+</PlatformSection>
+
+<PlatformSection supported={["java.spring", "java.spring-boot"]}>
+The `sentry-opentelemetry-agentless-spring` dependency combines all modules and dependencies needed to use Sentry with OpenTelemetry and Spring.
+</PlatformSection>
+
+<PlatformSection supported={["java.spring", "java.spring-boot"]} notSupported={["java"]}>
+If you're unsure whether to use the Java Agent, please have a look at [OpenTelemetry documentation](https://opentelemetry.io/docs/zero-code/java/spring-boot-starter/).
+</PlatformSection>
