feat(android): Add InternalSentrySdk.captureEnvelopeNonTerminating

Hybrid runtimes such as Flutter report unhandled exceptions that do not
terminate the process. Routing those through captureEnvelope ends the
session as crashed and starts a replacement one, which understates
crash-free session rates. The new entry point keeps the session alive
with the same id, increments its error count, and marks it
pending-unhandled so it finalizes as unhandled at its natural end.

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

Author: buenaflor

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

@@ -315,6 +315,7 @@ public abstract interface class io/sentry/android/core/IDebugImagesLoader {
 public final class io/sentry/android/core/InternalSentrySdk {
 	public fun <init> ()V
 	public static fun captureEnvelope ([BZ)Lio/sentry/protocol/SentryId;
+	public static fun captureEnvelopeNonTerminating ([B)Lio/sentry/protocol/SentryId;
 	public static fun getAppStartMeasurement ()Ljava/util/Map;
 	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;

sentry-android-core/build.gradle.kts

@@ -115,6 +115,7 @@ dependencies {
   testImplementation(libs.androidx.test.ext.junit)
   testImplementation(libs.androidx.test.runner)
   testImplementation(libs.awaitility.kotlin)
+  testImplementation(libs.google.truth)
   testImplementation(libs.mockito.kotlin)
   testImplementation(libs.mockito.inline)
   testImplementation(projects.sentryTestSupport)

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

@@ -34,6 +34,7 @@
 import io.sentry.util.TracingUtils;
 import java.io.ByteArrayInputStream;
 import java.io.File;
+import java.io.IOException;
 import java.io.InputStream;
 import java.util.ArrayList;
 import java.util.HashMap;
@@ -153,7 +154,12 @@ public static Map<String, Object> serializeScope(
    * - will not perform any sampling: it's up to the caller to take care of this<br>
    * - will enrich the envelope with a Session update if applicable<br>
    *
+   * <p>Unhandled events ({@code handled=false}) end the session as {@code crashed}. Prefer {@link
+   * #captureEnvelopeNonTerminating(byte[])} for hybrid runtimes where the process is expected to
+   * continue (e.g. Flutter).
+   *
    * @param envelopeData the serialized envelope data
+   * @param maybeStartNewSession if true, starts a new session after a crashed session is cleared
    * @return The Id (SentryId object) of the event, or null in case the envelope could not be
    *     captured
    */
@@ -163,14 +169,13 @@ public static SentryId captureEnvelope(
     final @NotNull IScopes scopes = ScopesAdapter.getInstance();
     final @NotNull SentryOptions options = scopes.getOptions();
 
-    try (final InputStream envelopeInputStream = new ByteArrayInputStream(envelopeData)) {
-      final @NotNull ISerializer serializer = options.getSerializer();
-      final @Nullable SentryEnvelope envelope =
-          options.getEnvelopeReader().read(envelopeInputStream);
-      if (envelope == null) {
-        return null;
-      }
+    final @Nullable SentryEnvelope envelope = readEnvelope(options, envelopeData);
+    if (envelope == null) {
+      return null;
+    }
 
+    try {
+      final @NotNull ISerializer serializer = options.getSerializer();
       final @NotNull List<SentryEnvelopeItem> envelopeItems = new ArrayList<>();
 
       // determine session state based on events inside envelope
@@ -207,12 +212,110 @@ public static SentryId captureEnvelope(
       final SentryEnvelope repackagedEnvelope =
           new SentryEnvelope(envelope.getHeader(), envelopeItems);
       return scopes.captureEnvelope(repackagedEnvelope);
-    } catch (Throwable t) {
-      options.getLogger().log(SentryLevel.ERROR, "Failed to capture envelope", t);
+    } catch (Exception e) {
+      options.getLogger().log(SentryLevel.ERROR, "Failed to capture envelope", e);
+    }
+    return null;
+  }
+
+  /**
+   * Captures the provided envelope for a non-terminating hybrid exception (e.g. Flutter).
+   *
+   * <p>Compared to {@link #captureEnvelope(byte[], boolean)} this method does <strong>not</strong>
+   * treat {@code handled=false} as a crash that ends the session. Instead it:
+   *
+   * <ul>
+   *   <li>marks the current session as pending-unhandled and increments the error count
+   *   <li>keeps session status {@code Ok} and the same session id on the scope
+   *   <li>does not attach a session update item to this envelope
+   *   <li>does not start a new session
+   *   <li>persists the current session so pending-unhandled survives process death
+   * </ul>
+   *
+   * <p>The session is finalized later by normal lifecycle ({@code endSession} / background /
+   * previous-session recovery) as {@code unhandled}, unless a native crash escalates it to {@code
+   * crashed}.
+   *
+   * <p>Same as {@link #captureEnvelope(byte[], boolean)}, this method will not enrich events, run
+   * {@code beforeSend}, or sample — the caller is responsible for that.
+   *
+   * @param envelopeData the serialized envelope data
+   * @return the id of the captured envelope, or null if capture failed
+   */
+  @Nullable
+  public static SentryId captureEnvelopeNonTerminating(final @NotNull byte[] envelopeData) {
+    final @NotNull IScopes scopes = ScopesAdapter.getInstance();
+    final @NotNull SentryOptions options = scopes.getOptions();
+
+    final @Nullable SentryEnvelope envelope = readEnvelope(options, envelopeData);
+    if (envelope == null) {
+      return null;
+    }
+
+    try {
+      final @NotNull ISerializer serializer = options.getSerializer();
+      boolean markPendingUnhandled = false;
+      boolean addErrorsCount = false;
+      for (SentryEnvelopeItem item : envelope.getItems()) {
+        final SentryEvent event = item.getEvent(serializer);
+        if (event != null) {
+          if (event.getUnhandledException() != null) {
+            markPendingUnhandled = true;
+            addErrorsCount = true;
+          } else if (event.isErrored()) {
+            addErrorsCount = true;
+          }
+        }
+      }
+
+      if (markPendingUnhandled || addErrorsCount) {
+        final boolean pending = markPendingUnhandled;
+        final boolean addErrors = addErrorsCount;
+        scopes.configureScope(
+            scope -> {
+              scope.withSession(
+                  session -> {
+                    if (session != null) {
+                      final boolean updated =
+                          pending
+                              ? session.markPendingUnhandled()
+                              : session.update(null, null, addErrors, null);
+                      if (updated && options.getEnvelopeDiskCache() instanceof EnvelopeCache) {
+                        ((EnvelopeCache) options.getEnvelopeDiskCache())
+                            .persistCurrentSession(session);
+                      }
+                    } else {
+                      options
+                          .getLogger()
+                          .log(INFO, "Session is null on captureEnvelopeNonTerminating");
+                    }
+                  });
+            });
+      }
+
+      // Capture the original envelope as-is (no session item attached).
+      return scopes.captureEnvelope(envelope);
+    } catch (Exception e) {
+      options.getLogger().log(SentryLevel.ERROR, "Failed to capture envelope", e);
     }
     return null;
   }
 
+  /**
+   * Reads an envelope from the given bytes. Besides the declared {@link IOException}, {@link
+   * io.sentry.IEnvelopeReader#read(InputStream)} also rejects malformed payloads with an unchecked
+   * {@link IllegalArgumentException}, hence the broader catch.
+   */
+  private static @Nullable SentryEnvelope readEnvelope(
+      final @NotNull SentryOptions options, final @NotNull byte[] envelopeData) {
+    try (final InputStream envelopeInputStream = new ByteArrayInputStream(envelopeData)) {
+      return options.getEnvelopeReader().read(envelopeInputStream);
+    } catch (Exception e) {
+      options.getLogger().log(SentryLevel.ERROR, "Failed to read envelope", e);
+      return null;
+    }
+  }
+
   public static Map<String, Object> getAppStartMeasurement() {
     final @NotNull AppStartMetrics metrics = AppStartMetrics.getInstance();
     final @NotNull List<Map<String, Object>> spans = new ArrayList<>();

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

@@ -5,6 +5,7 @@ import android.content.ContentProvider
 import android.content.Context
 import androidx.test.core.app.ApplicationProvider
 import androidx.test.ext.junit.runners.AndroidJUnit4
+import com.google.common.truth.Truth.assertThat
 import io.sentry.Breadcrumb
 import io.sentry.Hint
 import io.sentry.IScope
@@ -22,6 +23,7 @@ import io.sentry.Session
 import io.sentry.SpanId
 import io.sentry.android.core.performance.ActivityLifecycleTimeSpan
 import io.sentry.android.core.performance.AppStartMetrics
+import io.sentry.cache.EnvelopeCache
 import io.sentry.exception.ExceptionMechanismException
 import io.sentry.protocol.App
 import io.sentry.protocol.Contexts
@@ -107,6 +109,21 @@ class InternalSentrySdkTest {
       InternalSentrySdk.captureEnvelope(data, maybeStartNewSession)
     }
 
+    fun captureEnvelopeNonTerminatingWithEvent(event: SentryEvent = SentryEvent()) {
+      val options = Sentry.getCurrentScopes().options
+      val eventId = SentryId()
+      val header = SentryEnvelopeHeader(eventId)
+      val eventItem = SentryEnvelopeItem.fromEvent(options.serializer, event)
+
+      val envelope = SentryEnvelope(header, listOf(eventItem))
+
+      val outputStream = ByteArrayOutputStream()
+      options.serializer.serialize(envelope, outputStream)
+      val data = outputStream.toByteArray()
+
+      InternalSentrySdk.captureEnvelopeNonTerminating(data)
+    }
+
     fun createSentryEventWithUnhandledException(): SentryEvent {
       return SentryEvent(RuntimeException()).apply {
         val mechanism = Mechanism()
@@ -452,6 +469,110 @@ class InternalSentrySdkTest {
     assertNotEquals(capturedSession.sessionId, scopeRef.get().session!!.sessionId)
   }
 
+  @Test
+  fun `captureEnvelopeNonTerminating keeps the session Ok and marks it pending unhandled`() {
+    val fixture = Fixture()
+    fixture.init(context)
+
+    val originalSid = AtomicReference<String>()
+    Sentry.configureScope { scope -> originalSid.set(scope.session!!.sessionId) }
+
+    // when capture envelope is called with an unhandled event through the non-terminating API
+    fixture.captureEnvelopeNonTerminatingWithEvent(
+      fixture.createSentryEventWithUnhandledException()
+    )
+
+    // then only the original event envelope is captured, without a session item
+    assertThat(fixture.capturedEnvelopes).hasSize(1)
+    val capturedEnvelopeItems = fixture.capturedEnvelopes.first().items.toList()
+    assertThat(capturedEnvelopeItems).hasSize(1)
+    assertThat(capturedEnvelopeItems[0].header.type).isEqualTo(SentryItemType.Event)
+
+    // and the session stays alive on the scope, same id, marked pending unhandled
+    val scopeSession = AtomicReference<Session>()
+    Sentry.configureScope { scope -> scopeSession.set(scope.session) }
+    assertThat(scopeSession.get().status).isEqualTo(Session.State.Ok)
+    assertThat(scopeSession.get().isPendingUnhandled).isTrue()
+    assertThat(scopeSession.get().sessionId).isEqualTo(originalSid.get())
+
+    // and it is persisted so pending survives process death
+    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.isPendingUnhandled).isTrue()
+    assertThat(persistedSession.sessionId).isEqualTo(originalSid.get())
+  }
+
+  @Test
+  fun `captureEnvelopeNonTerminating then endSession finalizes the session as unhandled`() {
+    val fixture = Fixture()
+    fixture.init(context)
+
+    fixture.captureEnvelopeNonTerminatingWithEvent(
+      fixture.createSentryEventWithUnhandledException()
+    )
+    fixture.capturedEnvelopes.clear()
+
+    // when the session is ended by normal lifecycle
+    Sentry.endSession()
+
+    // then the ended session is captured as unhandled
+    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 `captureEnvelopeNonTerminating then a crash finalizes old session and starts a new one`() {
+    val fixture = Fixture()
+    fixture.init(context)
+
+    fixture.captureEnvelopeNonTerminatingWithEvent(
+      fixture.createSentryEventWithUnhandledException()
+    )
+    val pendingSession = AtomicReference<Session>()
+    Sentry.configureScope { scope -> pendingSession.set(scope.session) }
+    val oldSid = pendingSession.get().sessionId
+    assertThat(pendingSession.get().isPendingUnhandled).isTrue()
+    fixture.capturedEnvelopes.clear()
+
+    // when a subsequent hard crash is captured through the existing terminating API
+    fixture.captureEnvelopeWithEvent(fixture.createSentryEventWithUnhandledException(), true)
+
+    // then the crash envelope contains the finalized old session
+    assertThat(fixture.capturedEnvelopes).hasSize(2)
+    val crashEnvelopeItems = fixture.capturedEnvelopes.last().items.toList()
+    assertThat(crashEnvelopeItems).hasSize(2)
+    assertThat(crashEnvelopeItems[0].header.type).isEqualTo(SentryItemType.Event)
+    assertThat(crashEnvelopeItems[1].header.type).isEqualTo(SentryItemType.Session)
+    val crashedSession =
+      fixture.options.serializer.deserialize(
+        InputStreamReader(ByteArrayInputStream(crashEnvelopeItems[1].data)),
+        Session::class.java,
+      )!!
+    assertThat(crashedSession.status).isEqualTo(Session.State.Crashed)
+    assertThat(crashedSession.isPendingUnhandled).isFalse()
+    assertThat(crashedSession.sessionId).isEqualTo(oldSid)
+
+    // and a new Ok session with a different id is active
+    val activeSession = AtomicReference<Session>()
+    Sentry.configureScope { scope -> activeSession.set(scope.session) }
+    assertThat(activeSession.get().status).isEqualTo(Session.State.Ok)
+    assertThat(activeSession.get().isPendingUnhandled).isFalse()
+    assertThat(activeSession.get().sessionId).isNotEqualTo(oldSid)
+  }
+
   @Test
   fun `getAppStartMeasurement returns correct serialized data from the app start instance`() {
     Fixture().mockFinishedAppStart()

sentry/api/sentry.api

@@ -2497,6 +2497,10 @@ public abstract interface class io/sentry/Scope$IWithPropagationContext {
 	public abstract fun accept (Lio/sentry/PropagationContext;)V
 }
 
+public abstract interface class io/sentry/Scope$IWithSession {
+	public abstract fun accept (Lio/sentry/Session;)V
+}
+
 public abstract interface class io/sentry/Scope$IWithTransaction {
 	public abstract fun accept (Lio/sentry/ITransaction;)V
 }

sentry/src/main/java/io/sentry/Scope.java

@@ -1018,7 +1018,8 @@ public Session withSession(final @NotNull IWithSession sessionCallback) {
   }
 
   /** The IWithSession callback */
-  interface IWithSession {
+  @ApiStatus.Internal
+  public interface IWithSession {
 
     /**
      * The accept method of the callback