From 5f8d424f46e1fd7da9004259e555d04b6a092f07 Mon Sep 17 00:00:00 2001 From: lcian Date: Wed, 12 Feb 2025 13:49:26 +0100 Subject: [PATCH 1/4] feat(java): add Reactor integration docs --- .../java/common/integrations/reactor.mdx | 127 ++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 docs/platforms/java/common/integrations/reactor.mdx diff --git a/docs/platforms/java/common/integrations/reactor.mdx b/docs/platforms/java/common/integrations/reactor.mdx new file mode 100644 index 0000000000000..0a0106316dbdb --- /dev/null +++ b/docs/platforms/java/common/integrations/reactor.mdx @@ -0,0 +1,127 @@ +--- +title: Reactor Integration +description: "Learn how to capture errors, breadcrumbs and traces for your reactive applications." +--- + +Sentry's [Reactor](https://projectreactor.io/) integration provides a set of utilities to use Sentry with Reactor. + +Using the utilities ensures that your errors and traces are always enriched with the correct context and breadcrumbs. +Due to how Reactor works under the hood, if you don't use this integration, you might run into issues such as unrelated breadcrumbs appearing the events that are sent to Sentry within the context of Reactive Streams. + +If you're using Spring Boot WebFlux, you just need to install our [Spring Boot SDK](/platforms/java/guides/spring-boot/) and the Reactor integration will be automatically configured and enabled under the hood. + +Otherwise, read on to learn how to install and use the Sentry Reactor integration. + +## Install + +To install use: + +```groovy {tabTitle:Gradle} +implementation 'io.sentry:sentry-reactor:{{@inject packages.version('sentry.java.reactor', '8.3.0') }}' +``` + +```xml {tabTitle:Maven} + + io.sentry + sentry-reactor + {{@inject packages.version('sentry.java.reactor', '8.3.0') }} + +``` + +```scala {tabTitle: SBT} +libraryDependencies += "io.sentry" % "sentry-reactor" % "{{@inject packages.version('sentry.java.reactor', '8.3.0') }}" +``` + +For other dependency managers, check out the [central Maven repository](https://search.maven.org/artifact/io.sentry/sentry-reactor). + +Make sure your dependencies include `io.micrometer:context-propagation` version `1.0.2` or later, and `io.projectreactor:reactor-core` version `3.5.3` or later, as those are required for the integration to work. + +## Set Up + +Enable automatic context propagation: +```java +import reactor.core.publisher.Hooks; +// ... +Hooks.enableAutomaticContextPropagation(); +``` + +```kotlin +import reactor.core.publisher.Hooks +// ... +Hooks.enableAutomaticContextPropagation() +``` + +Then, enable the `SentryReactorThreadLocalAccessor`: +```java +import io.micrometer.context.ContextRegistry; +import io.sentry.reactor.SentryReactorThreadLocalAccessor; +// ... +ContextRegistry.getInstance().registerThreadLocalAccessor(SentryReactorThreadLocalAccessor()); +``` + +```kotlin +import io.micrometer.context.ContextRegistry +import io.sentry.reactor.SentryReactorThreadLocalAccessor +// ... +ContextRegistry.getInstance().registerThreadLocalAccessor(SentryReactorThreadLocalAccessor()) +``` + +## Usage + +Wrap your `Mono` and `Flux` objects using the `SentryReactorUtils.withSentry` function to enable correct capturing of errors, breadcrumbs and traces in the context of your Reactive Streams. +This will execute your publisher in the context of *forked current scopes*, which should be the default for most use cases. + +For example: +```java +import reactor.core.publisher.Mono; +import io.sentry.Sentry; +import io.sentry.ISpan; +import io.sentry.ITransaction; +import io.sentry.TransactionOptions; + +TransactionOptions txOptions = new TransactionOptions(); +txOptions.setBindToScope(true); +ITransaction tx = Sentry.startTransaction("Transaction", "op", txOptions); +ISpan child = tx.startChild("Outside Mono", "op") +Sentry.captureMessage("Message outside Mono") +child.finish() +String result = SentryReactorUtils.withSentry( + Mono.just("hello") + .map({ (it) -> + ISpan span = Sentry.getCurrentScopes().transaction.startChild("Inside Mono", "map"); + Sentry.captureMessage("Message inside Mono"); + span.finish(); + return it; + }) +).block(); +System.out.println(result); +tx.finish(); +``` + +```kotlin +import reactor.core.publisher.Mono +import io.sentry.Sentry +import io.sentry.TransactionOptions + +val tx = Sentry.startTransaction("Transaction Mono", "op", TransactionOptions().also { it.isBindToScope = true }) +val child = tx.startChild("Outside Mono", "op") +Sentry.captureMessage("Message outside Mono") +child.finish() +val result = SentryReactorUtils.withSentry( + Mono.just("hello") + .map { it -> + val span = Sentry.getCurrentScopes().transaction?.startChild("Inside Mono", "map") + Sentry.captureMessage("Message inside Mono") + span?.finish() + it + } +).block() +println(result) +tx.finish() +``` + +For more complex use cases, you can also use `SentryReactorUtils.withSentryForkedRoots` to fork the root scopes or `SentryReactorUtils.withSentryScopes` to wrap the operation in arbitrary scopes. + +For more information on scopes and scope forking, please consult our [scopes documentation](https://docs.sentry.io/platforms/java/enriching-events/scopes). + +You can also consult our GitHub repository for practical examples on how to use our Reactor integration with Spring WebFlux with [Spring Boot 2](https://github.com/getsentry/sentry-java/tree/main/sentry-samples/sentry-samples-spring-boot-webflux) and [Spring Boot 3](https://github.com/getsentry/sentry-java/tree/main/sentry-samples/sentry-samples-spring-boot-webflux-jakarta). From c593fe329357da67550dd39eb5993d073e04f0c7 Mon Sep 17 00:00:00 2001 From: Lorenzo Cian Date: Fri, 14 Feb 2025 10:27:46 +0100 Subject: [PATCH 2/4] Update docs/platforms/java/common/integrations/reactor.mdx Co-authored-by: Alex Krawiec --- docs/platforms/java/common/integrations/reactor.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/java/common/integrations/reactor.mdx b/docs/platforms/java/common/integrations/reactor.mdx index 0a0106316dbdb..c578273d6f554 100644 --- a/docs/platforms/java/common/integrations/reactor.mdx +++ b/docs/platforms/java/common/integrations/reactor.mdx @@ -6,7 +6,7 @@ description: "Learn how to capture errors, breadcrumbs and traces for your react Sentry's [Reactor](https://projectreactor.io/) integration provides a set of utilities to use Sentry with Reactor. Using the utilities ensures that your errors and traces are always enriched with the correct context and breadcrumbs. -Due to how Reactor works under the hood, if you don't use this integration, you might run into issues such as unrelated breadcrumbs appearing the events that are sent to Sentry within the context of Reactive Streams. +Due to how Reactor works under the hood, if you don't use this integration, you might run into issues such as unrelated breadcrumbs appearing in the events that are sent to Sentry within the context of Reactive Streams. If you're using Spring Boot WebFlux, you just need to install our [Spring Boot SDK](/platforms/java/guides/spring-boot/) and the Reactor integration will be automatically configured and enabled under the hood. From 54ef432bda693ebd1a87a40dae2b735e14928ca6 Mon Sep 17 00:00:00 2001 From: Lorenzo Cian Date: Fri, 14 Feb 2025 10:27:53 +0100 Subject: [PATCH 3/4] Update docs/platforms/java/common/integrations/reactor.mdx Co-authored-by: Alex Krawiec --- docs/platforms/java/common/integrations/reactor.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/java/common/integrations/reactor.mdx b/docs/platforms/java/common/integrations/reactor.mdx index c578273d6f554..9c24cbd56f58e 100644 --- a/docs/platforms/java/common/integrations/reactor.mdx +++ b/docs/platforms/java/common/integrations/reactor.mdx @@ -12,7 +12,7 @@ If you're using Spring Boot WebFlux, you just need to install our [Spring Boot S Otherwise, read on to learn how to install and use the Sentry Reactor integration. -## Install +## Installation To install use: From a03a2412aa0cf95b702bb2f7aeea0d55cfb0b239 Mon Sep 17 00:00:00 2001 From: Lorenzo Cian Date: Mon, 17 Feb 2025 12:27:43 +0100 Subject: [PATCH 4/4] Update reactor.mdx remove unneeded step --- .../java/common/integrations/reactor.mdx | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/docs/platforms/java/common/integrations/reactor.mdx b/docs/platforms/java/common/integrations/reactor.mdx index 9c24cbd56f58e..c3836ff6ddece 100644 --- a/docs/platforms/java/common/integrations/reactor.mdx +++ b/docs/platforms/java/common/integrations/reactor.mdx @@ -51,21 +51,6 @@ import reactor.core.publisher.Hooks Hooks.enableAutomaticContextPropagation() ``` -Then, enable the `SentryReactorThreadLocalAccessor`: -```java -import io.micrometer.context.ContextRegistry; -import io.sentry.reactor.SentryReactorThreadLocalAccessor; -// ... -ContextRegistry.getInstance().registerThreadLocalAccessor(SentryReactorThreadLocalAccessor()); -``` - -```kotlin -import io.micrometer.context.ContextRegistry -import io.sentry.reactor.SentryReactorThreadLocalAccessor -// ... -ContextRegistry.getInstance().registerThreadLocalAccessor(SentryReactorThreadLocalAccessor()) -``` - ## Usage Wrap your `Mono` and `Flux` objects using the `SentryReactorUtils.withSentry` function to enable correct capturing of errors, breadcrumbs and traces in the context of your Reactive Streams.