Implement local scope by adding overloads to the capture methods that accept a ScopeCallback (#2084)

* Add localScope to captureException, captureMessage in Hub.java and Sentry.java

* add overloads with scope callback for captureEvent, add local scope methods to Sentry.java, adapt tests, use correct methods in HubAdapter

* update sentry.api to reflect the new methods, run spotless, adapt test failing due to method overload ambiguity

* change User facing api surface by making ScopeCallback not null, improve tests

* add changelog

* implement suggested change

* add missing newLine in CHANGELOG, make Scope final

* use correct PR number

Co-authored-by: Lukas Bloder <[email protected]>

Author: adinauer

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### Features
+
+- Implement local scope by adding overloads to the capture methods that accept a ScopeCallback ([#2084](https://github.com/getsentry/sentry-java/pull/2084))
+
 ## 6.0.0
 
 ### Sentry Self-hosted Compatibility

sentry-graphql/src/test/kotlin/io/sentry/graphql/SentryDataFetcherExceptionHandlerTest.kt

@@ -6,6 +6,7 @@ import com.nhaarman.mockitokotlin2.mock
 import com.nhaarman.mockitokotlin2.verify
 import graphql.execution.DataFetcherExceptionHandler
 import graphql.execution.DataFetcherExceptionHandlerParameters
+import io.sentry.Hint
 import io.sentry.IHub
 import kotlin.test.Test
 
@@ -21,7 +22,7 @@ class SentryDataFetcherExceptionHandlerTest {
         val parameters = DataFetcherExceptionHandlerParameters.newExceptionParameters().exception(exception).build()
         handler.onException(parameters)
 
-        verify(hub).captureException(eq(exception), anyOrNull())
+        verify(hub).captureException(eq(exception), anyOrNull<Hint>())
         verify(delegate).onException(parameters)
     }
 }

sentry/api/sentry.api

@@ -208,8 +208,11 @@ public final class io/sentry/Hub : io/sentry/IHub {
 	public fun bindClient (Lio/sentry/ISentryClient;)V
 	public fun captureEnvelope (Lio/sentry/SentryEnvelope;Lio/sentry/Hint;)Lio/sentry/protocol/SentryId;
 	public fun captureEvent (Lio/sentry/SentryEvent;Lio/sentry/Hint;)Lio/sentry/protocol/SentryId;
+	public fun captureEvent (Lio/sentry/SentryEvent;Lio/sentry/Hint;Lio/sentry/ScopeCallback;)Lio/sentry/protocol/SentryId;
 	public fun captureException (Ljava/lang/Throwable;Lio/sentry/Hint;)Lio/sentry/protocol/SentryId;
+	public fun captureException (Ljava/lang/Throwable;Lio/sentry/Hint;Lio/sentry/ScopeCallback;)Lio/sentry/protocol/SentryId;
 	public fun captureMessage (Ljava/lang/String;Lio/sentry/SentryLevel;)Lio/sentry/protocol/SentryId;
+	public fun captureMessage (Ljava/lang/String;Lio/sentry/SentryLevel;Lio/sentry/ScopeCallback;)Lio/sentry/protocol/SentryId;
 	public fun captureTransaction (Lio/sentry/protocol/SentryTransaction;Lio/sentry/TraceState;Lio/sentry/Hint;Lio/sentry/ProfilingTraceData;)Lio/sentry/protocol/SentryId;
 	public fun captureUserFeedback (Lio/sentry/UserFeedback;)V
 	public fun clearBreadcrumbs ()V
@@ -248,8 +251,11 @@ public final class io/sentry/HubAdapter : io/sentry/IHub {
 	public fun bindClient (Lio/sentry/ISentryClient;)V
 	public fun captureEnvelope (Lio/sentry/SentryEnvelope;Lio/sentry/Hint;)Lio/sentry/protocol/SentryId;
 	public fun captureEvent (Lio/sentry/SentryEvent;Lio/sentry/Hint;)Lio/sentry/protocol/SentryId;
+	public fun captureEvent (Lio/sentry/SentryEvent;Lio/sentry/Hint;Lio/sentry/ScopeCallback;)Lio/sentry/protocol/SentryId;
 	public fun captureException (Ljava/lang/Throwable;Lio/sentry/Hint;)Lio/sentry/protocol/SentryId;
+	public fun captureException (Ljava/lang/Throwable;Lio/sentry/Hint;Lio/sentry/ScopeCallback;)Lio/sentry/protocol/SentryId;
 	public fun captureMessage (Ljava/lang/String;Lio/sentry/SentryLevel;)Lio/sentry/protocol/SentryId;
+	public fun captureMessage (Ljava/lang/String;Lio/sentry/SentryLevel;Lio/sentry/ScopeCallback;)Lio/sentry/protocol/SentryId;
 	public fun captureTransaction (Lio/sentry/protocol/SentryTransaction;Lio/sentry/TraceState;Lio/sentry/Hint;Lio/sentry/ProfilingTraceData;)Lio/sentry/protocol/SentryId;
 	public fun captureUserFeedback (Lio/sentry/UserFeedback;)V
 	public fun clearBreadcrumbs ()V
@@ -303,10 +309,16 @@ public abstract interface class io/sentry/IHub {
 	public abstract fun captureEnvelope (Lio/sentry/SentryEnvelope;Lio/sentry/Hint;)Lio/sentry/protocol/SentryId;
 	public fun captureEvent (Lio/sentry/SentryEvent;)Lio/sentry/protocol/SentryId;
 	public abstract fun captureEvent (Lio/sentry/SentryEvent;Lio/sentry/Hint;)Lio/sentry/protocol/SentryId;
+	public abstract fun captureEvent (Lio/sentry/SentryEvent;Lio/sentry/Hint;Lio/sentry/ScopeCallback;)Lio/sentry/protocol/SentryId;
+	public fun captureEvent (Lio/sentry/SentryEvent;Lio/sentry/ScopeCallback;)Lio/sentry/protocol/SentryId;
 	public fun captureException (Ljava/lang/Throwable;)Lio/sentry/protocol/SentryId;
 	public abstract fun captureException (Ljava/lang/Throwable;Lio/sentry/Hint;)Lio/sentry/protocol/SentryId;
+	public abstract fun captureException (Ljava/lang/Throwable;Lio/sentry/Hint;Lio/sentry/ScopeCallback;)Lio/sentry/protocol/SentryId;
+	public fun captureException (Ljava/lang/Throwable;Lio/sentry/ScopeCallback;)Lio/sentry/protocol/SentryId;
 	public fun captureMessage (Ljava/lang/String;)Lio/sentry/protocol/SentryId;
+	public fun captureMessage (Ljava/lang/String;Lio/sentry/ScopeCallback;)Lio/sentry/protocol/SentryId;
 	public abstract fun captureMessage (Ljava/lang/String;Lio/sentry/SentryLevel;)Lio/sentry/protocol/SentryId;
+	public abstract fun captureMessage (Ljava/lang/String;Lio/sentry/SentryLevel;Lio/sentry/ScopeCallback;)Lio/sentry/protocol/SentryId;
 	public fun captureTransaction (Lio/sentry/protocol/SentryTransaction;Lio/sentry/Hint;)Lio/sentry/protocol/SentryId;
 	public fun captureTransaction (Lio/sentry/protocol/SentryTransaction;Lio/sentry/TraceState;)Lio/sentry/protocol/SentryId;
 	public fun captureTransaction (Lio/sentry/protocol/SentryTransaction;Lio/sentry/TraceState;Lio/sentry/Hint;)Lio/sentry/protocol/SentryId;
@@ -539,8 +551,11 @@ public final class io/sentry/NoOpHub : io/sentry/IHub {
 	public fun bindClient (Lio/sentry/ISentryClient;)V
 	public fun captureEnvelope (Lio/sentry/SentryEnvelope;Lio/sentry/Hint;)Lio/sentry/protocol/SentryId;
 	public fun captureEvent (Lio/sentry/SentryEvent;Lio/sentry/Hint;)Lio/sentry/protocol/SentryId;
+	public fun captureEvent (Lio/sentry/SentryEvent;Lio/sentry/Hint;Lio/sentry/ScopeCallback;)Lio/sentry/protocol/SentryId;
 	public fun captureException (Ljava/lang/Throwable;Lio/sentry/Hint;)Lio/sentry/protocol/SentryId;
+	public fun captureException (Ljava/lang/Throwable;Lio/sentry/Hint;Lio/sentry/ScopeCallback;)Lio/sentry/protocol/SentryId;
 	public fun captureMessage (Ljava/lang/String;Lio/sentry/SentryLevel;)Lio/sentry/protocol/SentryId;
+	public fun captureMessage (Ljava/lang/String;Lio/sentry/SentryLevel;Lio/sentry/ScopeCallback;)Lio/sentry/protocol/SentryId;
 	public fun captureTransaction (Lio/sentry/protocol/SentryTransaction;Lio/sentry/TraceState;Lio/sentry/Hint;Lio/sentry/ProfilingTraceData;)Lio/sentry/protocol/SentryId;
 	public fun captureUserFeedback (Lio/sentry/UserFeedback;)V
 	public fun clearBreadcrumbs ()V
@@ -842,10 +857,16 @@ public final class io/sentry/Sentry {
 	public static fun bindClient (Lio/sentry/ISentryClient;)V
 	public static fun captureEvent (Lio/sentry/SentryEvent;)Lio/sentry/protocol/SentryId;
 	public static fun captureEvent (Lio/sentry/SentryEvent;Lio/sentry/Hint;)Lio/sentry/protocol/SentryId;
+	public static fun captureEvent (Lio/sentry/SentryEvent;Lio/sentry/Hint;Lio/sentry/ScopeCallback;)Lio/sentry/protocol/SentryId;
+	public static fun captureEvent (Lio/sentry/SentryEvent;Lio/sentry/ScopeCallback;)Lio/sentry/protocol/SentryId;
 	public static fun captureException (Ljava/lang/Throwable;)Lio/sentry/protocol/SentryId;
 	public static fun captureException (Ljava/lang/Throwable;Lio/sentry/Hint;)Lio/sentry/protocol/SentryId;
+	public static fun captureException (Ljava/lang/Throwable;Lio/sentry/Hint;Lio/sentry/ScopeCallback;)Lio/sentry/protocol/SentryId;
+	public static fun captureException (Ljava/lang/Throwable;Lio/sentry/ScopeCallback;)Lio/sentry/protocol/SentryId;
 	public static fun captureMessage (Ljava/lang/String;)Lio/sentry/protocol/SentryId;
+	public static fun captureMessage (Ljava/lang/String;Lio/sentry/ScopeCallback;)Lio/sentry/protocol/SentryId;
 	public static fun captureMessage (Ljava/lang/String;Lio/sentry/SentryLevel;)Lio/sentry/protocol/SentryId;
+	public static fun captureMessage (Ljava/lang/String;Lio/sentry/SentryLevel;Lio/sentry/ScopeCallback;)Lio/sentry/protocol/SentryId;
 	public static fun captureUserFeedback (Lio/sentry/UserFeedback;)V
 	public static fun clearBreadcrumbs ()V
 	public static fun close ()V

sentry/src/main/java/io/sentry/Hub.java

@@ -76,6 +76,21 @@ public boolean isEnabled() {
   @Override
   public @NotNull SentryId captureEvent(
       final @NotNull SentryEvent event, final @Nullable Hint hint) {
+    return captureEventInternal(event, hint, null);
+  }
+
+  @Override
+  public @NotNull SentryId captureEvent(
+      final @NotNull SentryEvent event,
+      final @Nullable Hint hint,
+      final @NotNull ScopeCallback callback) {
+    return captureEventInternal(event, hint, callback);
+  }
+
+  private @NotNull SentryId captureEventInternal(
+      final @NotNull SentryEvent event,
+      final @Nullable Hint hint,
+      final @Nullable ScopeCallback scopeCallback) {
     SentryId sentryId = SentryId.EMPTY_ID;
     if (!isEnabled()) {
       options
@@ -88,7 +103,10 @@ public boolean isEnabled() {
       try {
         assignTraceContext(event);
         final StackItem item = stack.peek();
-        sentryId = item.getClient().captureEvent(event, item.getScope(), hint);
+
+        final Scope scope = buildLocalScope(item.getScope(), scopeCallback);
+
+        sentryId = item.getClient().captureEvent(event, scope, hint);
         this.lastEventId = sentryId;
       } catch (Throwable e) {
         options
@@ -103,6 +121,21 @@ public boolean isEnabled() {
   @Override
   public @NotNull SentryId captureMessage(
       final @NotNull String message, final @NotNull SentryLevel level) {
+    return captureMessageInternal(message, level, null);
+  }
+
+  @Override
+  public @NotNull SentryId captureMessage(
+      final @NotNull String message,
+      final @NotNull SentryLevel level,
+      final @NotNull ScopeCallback callback) {
+    return captureMessageInternal(message, level, callback);
+  }
+
+  private @NotNull SentryId captureMessageInternal(
+      final @NotNull String message,
+      final @NotNull SentryLevel level,
+      final @Nullable ScopeCallback scopeCallback) {
     SentryId sentryId = SentryId.EMPTY_ID;
     if (!isEnabled()) {
       options
@@ -115,7 +148,10 @@ public boolean isEnabled() {
     } else {
       try {
         final StackItem item = stack.peek();
-        sentryId = item.getClient().captureMessage(message, level, item.getScope());
+
+        final Scope scope = buildLocalScope(item.getScope(), scopeCallback);
+
+        sentryId = item.getClient().captureMessage(message, level, scope);
       } catch (Throwable e) {
         options.getLogger().log(SentryLevel.ERROR, "Error while capturing message: " + message, e);
       }
@@ -154,6 +190,22 @@ public boolean isEnabled() {
   @Override
   public @NotNull SentryId captureException(
       final @NotNull Throwable throwable, final @Nullable Hint hint) {
+    return captureExceptionInternal(throwable, hint, null);
+  }
+
+  @Override
+  public @NotNull SentryId captureException(
+      final @NotNull Throwable throwable,
+      final @Nullable Hint hint,
+      final @NotNull ScopeCallback callback) {
+
+    return captureExceptionInternal(throwable, hint, callback);
+  }
+
+  private @NotNull SentryId captureExceptionInternal(
+      final @NotNull Throwable throwable,
+      final @Nullable Hint hint,
+      final @Nullable ScopeCallback scopeCallback) {
     SentryId sentryId = SentryId.EMPTY_ID;
     if (!isEnabled()) {
       options
@@ -168,7 +220,10 @@ public boolean isEnabled() {
         final StackItem item = stack.peek();
         final SentryEvent event = new SentryEvent(throwable);
         assignTraceContext(event);
-        sentryId = item.getClient().captureEvent(event, item.getScope(), hint);
+
+        final Scope scope = buildLocalScope(item.getScope(), scopeCallback);
+
+        sentryId = item.getClient().captureEvent(event, scope, hint);
       } catch (Throwable e) {
         options
             .getLogger()
@@ -761,4 +816,14 @@ SpanContext getSpanContext(final @NotNull Throwable throwable) {
     }
     return null;
   }
+
+  private Scope buildLocalScope(
+      final @NotNull Scope scope, final @Nullable ScopeCallback callback) {
+    if (callback != null) {
+      final Scope localScope = new Scope(scope);
+      callback.run(localScope);
+      return localScope;
+    }
+    return scope;
+  }
 }

sentry/src/main/java/io/sentry/HubAdapter.java

@@ -29,11 +29,23 @@ public boolean isEnabled() {
     return Sentry.captureEvent(event, hint);
   }
 
+  @Override
+  public @NotNull SentryId captureEvent(
+      @NotNull SentryEvent event, @Nullable Hint hint, @NotNull ScopeCallback callback) {
+    return Sentry.captureEvent(event, hint, callback);
+  }
+
   @Override
   public @NotNull SentryId captureMessage(@NotNull String message, @NotNull SentryLevel level) {
     return Sentry.captureMessage(message, level);
   }
 
+  @Override
+  public @NotNull SentryId captureMessage(
+      @NotNull String message, @NotNull SentryLevel level, @NotNull ScopeCallback callback) {
+    return Sentry.captureMessage(message, level, callback);
+  }
+
   @ApiStatus.Internal
   @Override
   public @NotNull SentryId captureEnvelope(@NotNull SentryEnvelope envelope, @Nullable Hint hint) {
@@ -45,6 +57,12 @@ public boolean isEnabled() {
     return Sentry.captureException(throwable, hint);
   }
 
+  @Override
+  public @NotNull SentryId captureException(
+      @NotNull Throwable throwable, @Nullable Hint hint, @NotNull ScopeCallback callback) {
+    return Sentry.captureException(throwable, hint, callback);
+  }
+
   @Override
   public void captureUserFeedback(@NotNull UserFeedback userFeedback) {
     Sentry.captureUserFeedback(userFeedback);

sentry/src/main/java/io/sentry/IHub.java

@@ -36,9 +36,35 @@ public interface IHub {
    * @return The Id (SentryId object) of the event
    */
   default @NotNull SentryId captureEvent(@NotNull SentryEvent event) {
-    return captureEvent(event, null);
+    return captureEvent(event, new Hint());
   }
 
+  /**
+   * Captures the event.
+   *
+   * @param event the event
+   * @param callback The callback to configure the scope for a single invocation.
+   * @return The Id (SentryId object) of the event
+   */
+  default @NotNull SentryId captureEvent(
+      @NotNull SentryEvent event, final @NotNull ScopeCallback callback) {
+    return captureEvent(event, new Hint(), callback);
+  }
+
+  /**
+   * Captures the event.
+   *
+   * @param event the event
+   * @param hint SDK specific but provides high level information about the origin of the event
+   * @param callback The callback to configure the scope for a single invocation.
+   * @return The Id (SentryId object) of the event
+   */
+  @NotNull
+  SentryId captureEvent(
+      final @NotNull SentryEvent event,
+      final @Nullable Hint hint,
+      final @NotNull ScopeCallback callback);
+
   /**
    * Captures the message.
    *
@@ -59,6 +85,30 @@ public interface IHub {
   @NotNull
   SentryId captureMessage(@NotNull String message, @NotNull SentryLevel level);
 
+  /**
+   * Captures the message.
+   *
+   * @param message The message to send.
+   * @param level The message level.
+   * @param callback The callback to configure the scope for a single invocation.
+   * @return The Id (SentryId object) of the event
+   */
+  @NotNull
+  SentryId captureMessage(
+      @NotNull String message, @NotNull SentryLevel level, @NotNull ScopeCallback callback);
+
+  /**
+   * Captures the message.
+   *
+   * @param message The message to send.
+   * @param callback The callback to configure the scope for a single invocation.
+   * @return The Id (SentryId object) of the event
+   */
+  default @NotNull SentryId captureMessage(
+      @NotNull String message, @NotNull ScopeCallback callback) {
+    return captureMessage(message, SentryLevel.INFO, callback);
+  }
+
   /**
    * Captures an envelope.
    *
@@ -96,9 +146,35 @@ public interface IHub {
    * @return The Id (SentryId object) of the event
    */
   default @NotNull SentryId captureException(@NotNull Throwable throwable) {
-    return captureException(throwable, null);
+    return captureException(throwable, new Hint());
   }
 
+  /**
+   * Captures the exception.
+   *
+   * @param throwable The exception.
+   * @param callback The callback to configure the scope for a single invocation.
+   * @return The Id (SentryId object) of the event
+   */
+  default @NotNull SentryId captureException(
+      @NotNull Throwable throwable, final @NotNull ScopeCallback callback) {
+    return captureException(throwable, new Hint(), callback);
+  }
+
+  /**
+   * Captures the exception.
+   *
+   * @param throwable The exception.
+   * @param hint SDK specific but provides high level information about the origin of the event
+   * @param callback The callback to configure the scope for a single invocation.
+   * @return The Id (SentryId object) of the event
+   */
+  @NotNull
+  SentryId captureException(
+      final @NotNull Throwable throwable,
+      final @Nullable Hint hint,
+      final @NotNull ScopeCallback callback);
+
   /**
    * Captures a manually created user feedback and sends it to Sentry.
    *

sentry/src/main/java/io/sentry/NoOpHub.java

@@ -30,11 +30,23 @@ public boolean isEnabled() {
     return SentryId.EMPTY_ID;
   }
 
+  @Override
+  public @NotNull SentryId captureEvent(
+      @NotNull SentryEvent event, @Nullable Hint hint, @NotNull ScopeCallback callback) {
+    return SentryId.EMPTY_ID;
+  }
+
   @Override
   public @NotNull SentryId captureMessage(@NotNull String message, @NotNull SentryLevel level) {
     return SentryId.EMPTY_ID;
   }
 
+  @Override
+  public @NotNull SentryId captureMessage(
+      @NotNull String message, @NotNull SentryLevel level, @NotNull ScopeCallback callback) {
+    return SentryId.EMPTY_ID;
+  }
+
   @Override
   public @NotNull SentryId captureEnvelope(@NotNull SentryEnvelope envelope, @Nullable Hint hint) {
     return SentryId.EMPTY_ID;
@@ -45,6 +57,12 @@ public boolean isEnabled() {
     return SentryId.EMPTY_ID;
   }
 
+  @Override
+  public @NotNull SentryId captureException(
+      @NotNull Throwable throwable, @Nullable Hint hint, @NotNull ScopeCallback callback) {
+    return SentryId.EMPTY_ID;
+  }
+
   @Override
   public void captureUserFeedback(@NotNull UserFeedback userFeedback) {}