feat(android): [Unhandled Sessions 4] Add session update API for unsampled hybrid errors (#5990)

* feat(android): Add session update for dropped hybrid errors

Hybrid SDKs skip captureEnvelopeNonTerminating when an error is unsampled,
so the session never records it. Expose the same non-terminating session
update without sending the event.

Co-authored-by: Cursor <cursoragent@cursor.com>

* changelog

Co-authored-by: Cursor <cursoragent@cursor.com>

* docs(android): Mention only sampling for the dropped-event session API

This path is for hybrid errors dropped by sample rate, not rate limiting.

Co-authored-by: Cursor <cursoragent@cursor.com>

* docs(android): Note that the dropped-event session API writes to disk

Persisting the session is synchronous so the unhandled marker is durable
by the time the call returns, which means callers must stay off the main
thread. Say so where hybrid SDK authors will read it.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: buenaflor

CHANGELOG.md

@@ -17,6 +17,7 @@
 ### Internal
 
 - Add `InternalSentrySdk.captureEnvelopeNonTerminating` for hybrid SDKs (e.g. Flutter) so unhandled exceptions that don't terminate the process no longer end the session as `crashed` ([#5921](https://github.com/getsentry/sentry-java/pull/5921))
+- Add `InternalSentrySdk.updateSessionForDroppedEventNonTerminating` so hybrid SDKs can still update the session when an error is dropped by sampling ([#5990](https://github.com/getsentry/sentry-java/pull/5990))
 
 ## 8.54.0
 

sentry-android-core/api/sentry-android-core.api

@@ -323,6 +323,7 @@ public final class io/sentry/android/core/InternalSentrySdk {
 	public static fun getCurrentScope ()Lio/sentry/IScope;
 	public static fun serializeScope (Landroid/content/Context;Lio/sentry/android/core/SentryAndroidOptions;Lio/sentry/IScope;)Ljava/util/Map;
 	public static fun setTrace (Ljava/lang/String;Ljava/lang/String;Ljava/lang/Double;Ljava/lang/Double;)V
+	public static fun updateSessionForDroppedEventNonTerminating (Z)V
 }
 
 public final class io/sentry/android/core/LoadClass : io/sentry/util/LoadClass {

sentry-android-core/src/main/java/io/sentry/android/core/InternalSentrySdk.java

@@ -264,6 +264,23 @@ public static SentryId captureEnvelopeNonTerminating(final @NotNull byte[] envel
     return scopes.captureEnvelope(envelope);
   }
 
+  /**
+   * Session side effects of {@link #captureEnvelopeNonTerminating(byte[])} without sending the
+   * event. Hybrid SDKs should call this when an error is dropped by sampling.
+   *
+   * <p>Do not call this for events dropped by {@code beforeSend} or ignored exception types.
+   *
+   * <p>Persisting the session is a blocking disk write on the calling thread, so call this off the
+   * main thread as the hybrid SDKs do. It is synchronous on purpose: a deferred write would not be
+   * on disk yet if the process dies right after this returns.
+   *
+   * @param crashed {@code true} if the dropped error was unhandled ({@code
+   *     mechanism.handled=false})
+   */
+  public static void updateSessionForDroppedEventNonTerminating(final boolean crashed) {
+    updateSessionNonTerminating(crashed);
+  }
+
   /**
    * Flags the current session for a non-terminating hybrid error and persists it before returning,
    * so the marker survives an immediate process death.

sentry-android-core/src/test/java/io/sentry/android/core/InternalSentrySdkTest.kt

@@ -612,6 +612,86 @@ class InternalSentrySdkTest {
     assertThat(activeSession.get().sessionId).isNotEqualTo(oldSid)
   }
 
+  @Test
+  fun `updateSessionForDroppedEventNonTerminating flags an unhandled error without sending an envelope`() {
+    val fixture = Fixture()
+    fixture.init(context)
+
+    val originalSid = AtomicReference<String>()
+    Sentry.configureScope { scope -> originalSid.set(scope.session!!.sessionId) }
+    fixture.capturedEnvelopes.clear()
+
+    InternalSentrySdk.updateSessionForDroppedEventNonTerminating(true)
+
+    assertThat(fixture.capturedEnvelopes).isEmpty()
+
+    val scopeSession = AtomicReference<Session>()
+    Sentry.configureScope { scope -> scopeSession.set(scope.session) }
+    assertThat(scopeSession.get().status).isEqualTo(Session.State.Ok)
+    assertThat(scopeSession.get().hasNonTerminatingUnhandledError()).isTrue()
+    assertThat(scopeSession.get().errorCount()).isEqualTo(1)
+    assertThat(scopeSession.get().sessionId).isEqualTo(originalSid.get())
+
+    val sessionFile = EnvelopeCache.getCurrentSessionFile(fixture.options.cacheDirPath!!)
+    val persistedSession =
+      fixture.options.serializer.deserialize(sessionFile.reader(), Session::class.java)!!
+    assertThat(persistedSession.status).isEqualTo(Session.State.Ok)
+    assertThat(persistedSession.hasNonTerminatingUnhandledError()).isTrue()
+    assertThat(persistedSession.errorCount()).isEqualTo(1)
+    assertThat(persistedSession.sessionId).isEqualTo(originalSid.get())
+  }
+
+  @Test
+  fun `updateSessionForDroppedEventNonTerminating increments errors for a handled error without sending an envelope`() {
+    val fixture = Fixture()
+    fixture.init(context)
+
+    val originalSid = AtomicReference<String>()
+    Sentry.configureScope { scope -> originalSid.set(scope.session!!.sessionId) }
+    fixture.capturedEnvelopes.clear()
+
+    InternalSentrySdk.updateSessionForDroppedEventNonTerminating(false)
+
+    assertThat(fixture.capturedEnvelopes).isEmpty()
+
+    val scopeSession = AtomicReference<Session>()
+    Sentry.configureScope { scope -> scopeSession.set(scope.session) }
+    assertThat(scopeSession.get().status).isEqualTo(Session.State.Ok)
+    assertThat(scopeSession.get().hasNonTerminatingUnhandledError()).isFalse()
+    assertThat(scopeSession.get().errorCount()).isEqualTo(1)
+    assertThat(scopeSession.get().sessionId).isEqualTo(originalSid.get())
+
+    val sessionFile = EnvelopeCache.getCurrentSessionFile(fixture.options.cacheDirPath!!)
+    val persistedSession =
+      fixture.options.serializer.deserialize(sessionFile.reader(), Session::class.java)!!
+    assertThat(persistedSession.status).isEqualTo(Session.State.Ok)
+    assertThat(persistedSession.hasNonTerminatingUnhandledError()).isFalse()
+    assertThat(persistedSession.errorCount()).isEqualTo(1)
+  }
+
+  @Test
+  fun `updateSessionForDroppedEventNonTerminating then endSession finalizes the session as unhandled`() {
+    val fixture = Fixture()
+    fixture.init(context)
+
+    InternalSentrySdk.updateSessionForDroppedEventNonTerminating(true)
+    fixture.capturedEnvelopes.clear()
+
+    Sentry.endSession()
+
+    val sessionItems =
+      fixture.capturedEnvelopes
+        .flatMap { it.items.toList() }
+        .filter { it.header.type == SentryItemType.Session }
+    assertThat(sessionItems).hasSize(1)
+    val endedSession =
+      fixture.options.serializer.deserialize(
+        InputStreamReader(ByteArrayInputStream(sessionItems[0].data)),
+        Session::class.java,
+      )!!
+    assertThat(endedSession.status).isEqualTo(Session.State.Unhandled)
+  }
+
   @Test
   fun `getAppStartMeasurement returns correct serialized data from the app start instance`() {
     Fixture().mockFinishedAppStart()