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 index ca7e559c59e71b..f41af8cd41cdec 100644 --- 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 docs page 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 new file mode 100644 index 00000000000000..0782ed78c8bfdf --- /dev/null +++ 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. + + diff --git a/docs/platforms/java/common/opentelemetry/setup/agent/auto-init.mdx b/docs/platforms/java/common/opentelemetry/setup/agent/auto-init.mdx new file mode 100644 index 00000000000000..feb025f6cd6e13 --- /dev/null +++ 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`. + + + +## Install + + + +## Usage + + + +## Debugging + + + +## Turn Off Exporter Error Messages + + diff --git a/docs/platforms/java/common/opentelemetry/setup/agent/index.mdx b/docs/platforms/java/common/opentelemetry/setup/agent/index.mdx new file mode 100644 index 00000000000000..df664c3caa9c8f --- /dev/null +++ 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 +--- + + + +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. + + + + + 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 new file mode 100644 index 00000000000000..3f52b7997a665d --- /dev/null +++ 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. + + + +## Install + + + +## Usage + + + +## Debugging + + + +## Turn Off Exporter Error Messages + + diff --git a/docs/platforms/java/common/opentelemetry/setup/agentless.mdx b/docs/platforms/java/common/opentelemetry/setup/agentless.mdx new file mode 100644 index 00000000000000..f2483a4e10307f --- /dev/null +++ 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 Java Agent, we also offer a dependency that allows you to use OpenTelemetry with Sentry. + +## Install + + + +## Usage + +You'll have to configure both OpenTelemetry and Sentry to see transactions in Sentry and have errors linked to transactions created by OpenTelemetry. + + diff --git a/docs/platforms/java/common/opentelemetry/setup/index.mdx b/docs/platforms/java/common/opentelemetry/setup/index.mdx new file mode 100644 index 00000000000000..a1f511afef62aa --- /dev/null +++ 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 + + + +For a guide on how to set up `sentry-opentelemetry-agent`, please have a look at the detailed Agent docs. + +## Agentless + + + +For a guide on how to set up agentless, please have a look at the detailed Agentless docs. diff --git a/docs/platforms/java/common/opentelemetry/usage/index.mdx b/docs/platforms/java/common/opentelemetry/usage/index.mdx new file mode 100644 index 00000000000000..e99811d760db05 --- /dev/null +++ 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. + + + +Please only enable headers you actually want to send to Sentry. Some may contain sensitive data like PII, cookies or tokens. + + + +#### 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 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. diff --git a/docs/platforms/java/common/tracing/instrumentation/opentelemetry.mdx b/docs/platforms/java/common/tracing/instrumentation/opentelemetry.mdx index db3fd045e475b4..078660c58ad04c 100644 --- 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. - - -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/). - - -## 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 - - - -### 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 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 - - - -### Usage - - - -### Debugging - - - -### Turn Off Exporter Error 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 - - - -### Usage - -You'll have to configure both OpenTelemetry and Sentry to see transactions in Sentry and have errors linked to transactions created by OpenTelemetry. - - - -## 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 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. +This page has moved to a top level page. diff --git a/platform-includes/performance/opentelemetry-install/without-java-agent/java.mdx b/platform-includes/performance/opentelemetry-install/without-java-agent/java.mdx index 93d4c89dada585..aaee1ea867478d 100644 --- 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 ``` -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 new file mode 100644 index 00000000000000..f029eae6ef0a1c --- /dev/null +++ b/platform-includes/performance/opentelemetry-setup/agent-auto-init-recommendation/disabled/java.mdx @@ -0,0 +1,3 @@ + +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. + 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 new file mode 100644 index 00000000000000..b8451ea12b4ce2 --- /dev/null +++ b/platform-includes/performance/opentelemetry-setup/agent-auto-init-recommendation/enabled/java.mdx @@ -0,0 +1,3 @@ + +We recommend letting the Java Agent take care of initializing Sentry as this way the SDK will be ready early in your applications lifecycle. + diff --git a/platform-includes/performance/opentelemetry-setup/agent-explanation/java.mdx b/platform-includes/performance/opentelemetry-setup/agent-explanation/java.mdx new file mode 100644 index 00000000000000..fb98d362fc68fc --- /dev/null +++ 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. + + + +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. + + + + +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/). + + +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 new file mode 100644 index 00000000000000..7922d190ecefd7 --- /dev/null +++ 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. + + +The `sentry-opentelemetry-agentless` dependency combines all modules and dependencies needed to use Sentry with OpenTelemetry. + + + +The `sentry-opentelemetry-agentless-spring` dependency combines all modules and dependencies needed to use Sentry with OpenTelemetry and Spring. + + + +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/). +