Add CoroutineExceptionHandler (#4259)

* Add CoroutineExceptionHandler

* tests

* changelog

* improve

* improve

* Update CHANGELOG.md

Author: lcian

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+### Features
+
+- Add `CoroutineExceptionHandler` for reporting uncaught exceptions in coroutines to Sentry ([#4259](https://github.com/getsentry/sentry-java/pull/4259))
+  - This is now part of `sentry-kotlin-extensions` and can be used together with `SentryContext` when launching a coroutine
+  - Any exceptions thrown in a coroutine when using the handler will be captured (not rethrown!) and reported to Sentry
+  - It's also possible to extend `CoroutineExceptionHandler` to implement custom behavior in addition to the one we provide by default
+
 ### Fixes
 
 - Use thread context classloader when available ([#4320](https://github.com/getsentry/sentry-java/pull/4320))

buildSrc/src/main/java/Config.kt

@@ -121,6 +121,8 @@ object Config {
 
         val coroutinesCore = "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.1"
 
+        val coroutinesAndroid = "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.1"
+
         val fragment = "androidx.fragment:fragment-ktx:1.3.5"
 
         val reactorCore = "io.projectreactor:reactor-core:3.5.3"
@@ -214,6 +216,7 @@ object Config {
         val leakCanaryInstrumentation = "com.squareup.leakcanary:leakcanary-android-instrumentation:2.14"
         val composeUiTestJunit4 = "androidx.compose.ui:ui-test-junit4:1.6.8"
         val okio = "com.squareup.okio:okio:1.13.0"
+        val coroutinesTest = "org.jetbrains.kotlinx:kotlinx-coroutines-test:1.6.1"
     }
 
     object QualityPlugins {

sentry-apollo-4/build.gradle.kts

@@ -41,7 +41,7 @@ dependencies {
     testImplementation(Config.TestLibs.mockitoInline)
     testImplementation(Config.TestLibs.mockWebserver)
     testImplementation(Config.Libs.apolloKotlin4)
-    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.7.3")
+    testImplementation(Config.TestLibs.coroutinesTest)
     testImplementation("org.jetbrains.kotlin:kotlin-reflect:2.0.0")
 }
 

sentry-kotlin-extensions/api/sentry-kotlin-extensions.api

@@ -10,3 +10,10 @@ public final class io/sentry/kotlin/SentryContext : kotlin/coroutines/AbstractCo
 	public synthetic fun updateThreadContext (Lkotlin/coroutines/CoroutineContext;)Ljava/lang/Object;
 }
 
+public class io/sentry/kotlin/SentryCoroutineExceptionHandler : kotlin/coroutines/AbstractCoroutineContextElement, kotlinx/coroutines/CoroutineExceptionHandler {
+	public fun <init> ()V
+	public fun <init> (Lio/sentry/IScopes;)V
+	public synthetic fun <init> (Lio/sentry/IScopes;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun handleException (Lkotlin/coroutines/CoroutineContext;Ljava/lang/Throwable;)V
+}
+

sentry-kotlin-extensions/build.gradle.kts

@@ -30,6 +30,7 @@ dependencies {
     testImplementation(Config.TestLibs.kotlinTestJunit)
     testImplementation(Config.TestLibs.mockitoKotlin)
     testImplementation(Config.Libs.coroutinesCore)
+    testImplementation(Config.TestLibs.coroutinesTest)
 }
 
 configure<SourceSetContainer> {

sentry-kotlin-extensions/src/main/java/io/sentry/kotlin/SentryCoroutineExceptionHandler.kt

@@ -0,0 +1,31 @@
+package io.sentry.kotlin
+
+import io.sentry.IScopes
+import io.sentry.ScopesAdapter
+import io.sentry.SentryEvent
+import io.sentry.SentryLevel
+import io.sentry.exception.ExceptionMechanismException
+import io.sentry.protocol.Mechanism
+import kotlinx.coroutines.CoroutineExceptionHandler
+import org.jetbrains.annotations.ApiStatus
+import kotlin.coroutines.AbstractCoroutineContextElement
+import kotlin.coroutines.CoroutineContext
+
+/**
+ * Captures exceptions thrown in coroutines (without rethrowing them) and reports them to Sentry as errors.
+ */
+@ApiStatus.Experimental
+public open class SentryCoroutineExceptionHandler(private val scopes: IScopes = ScopesAdapter.getInstance()) :
+    AbstractCoroutineContextElement(CoroutineExceptionHandler), CoroutineExceptionHandler {
+
+    override fun handleException(context: CoroutineContext, exception: Throwable) {
+        val mechanism = Mechanism().apply {
+            type = "CoroutineExceptionHandler"
+        }
+        // the current thread is not necessarily the one that threw the exception
+        val error = ExceptionMechanismException(mechanism, exception, Thread.currentThread())
+        val event = SentryEvent(error)
+        event.level = SentryLevel.ERROR
+        scopes.captureEvent(event)
+    }
+}

sentry-kotlin-extensions/src/test/java/io/sentry/kotlin/SentryCoroutineExceptionHandlerTest.kt

@@ -0,0 +1,80 @@
+package io.sentry.kotlin
+
+import io.sentry.IScopes
+import kotlinx.coroutines.GlobalScope
+import kotlinx.coroutines.async
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.test.runTest
+import org.mockito.kotlin.check
+import org.mockito.kotlin.mock
+import org.mockito.kotlin.verify
+import kotlin.test.Test
+import kotlin.test.assertSame
+import kotlin.test.assertTrue
+
+class SentryCoroutineExceptionHandlerTest {
+
+    class Fixture {
+        val scopes = mock<IScopes>()
+
+        fun getSut(): SentryCoroutineExceptionHandler {
+            return SentryCoroutineExceptionHandler(scopes)
+        }
+    }
+
+    @Test
+    fun `captures unhandled exception in launch coroutine`() = runTest {
+        val fixture = Fixture()
+        val handler = fixture.getSut()
+        val exception = RuntimeException("test")
+
+        GlobalScope.launch(handler) {
+            throw exception
+        }.join()
+
+        verify(fixture.scopes).captureEvent(
+            check {
+                assertSame(exception, it.throwable)
+            }
+        )
+    }
+
+    @Test
+    fun `captures unhandled exception in launch coroutine with child`() = runTest {
+        val fixture = Fixture()
+        val handler = fixture.getSut()
+        val exception = RuntimeException("test")
+
+        GlobalScope.launch(handler) {
+            launch {
+                throw exception
+            }.join()
+        }.join()
+
+        verify(fixture.scopes).captureEvent(
+            check {
+                assertSame(exception, it.throwable)
+            }
+        )
+    }
+
+    @Test
+    fun `captures unhandled exception in async coroutine`() = runTest {
+        val fixture = Fixture()
+        val handler = fixture.getSut()
+        val exception = RuntimeException("test")
+
+        val deferred = GlobalScope.async() {
+            throw exception
+        }
+        GlobalScope.launch(handler) {
+            deferred.await()
+        }.join()
+
+        verify(fixture.scopes).captureEvent(
+            check {
+                assertTrue { exception.toString().equals(it.throwable.toString()) } // stack trace will differ
+            }
+        )
+    }
+}

sentry-samples/sentry-samples-android/build.gradle.kts

@@ -150,5 +150,8 @@ dependencies {
     implementation(Config.Libs.composeCoil)
     implementation(Config.Libs.sentryNativeNdk)
 
+    implementation(projects.sentryKotlinExtensions)
+    implementation(Config.Libs.coroutinesAndroid)
+
     debugImplementation(Config.Libs.leakCanary)
 }

sentry-samples/sentry-samples-android/src/main/java/io/sentry/samples/android/CoroutinesUtil.kt

@@ -0,0 +1,16 @@
+package io.sentry.samples.android
+
+import io.sentry.kotlin.SentryContext
+import io.sentry.kotlin.SentryCoroutineExceptionHandler
+import kotlinx.coroutines.GlobalScope
+import kotlinx.coroutines.launch
+import java.lang.RuntimeException
+
+object CoroutinesUtil {
+
+    fun throwInCoroutine() {
+        GlobalScope.launch(SentryContext() + SentryCoroutineExceptionHandler()) {
+            throw RuntimeException("Exception in coroutine")
+        }
+    }
+}

sentry-samples/sentry-samples-android/src/main/java/io/sentry/samples/android/MainActivity.java

@@ -270,6 +270,11 @@ public void run() {
     binding.openFrameDataForSpans.setOnClickListener(
         view -> startActivity(new Intent(this, FrameDataForSpansActivity.class)));
 
+    binding.throwInCoroutine.setOnClickListener(
+        view -> {
+          CoroutinesUtil.INSTANCE.throwInCoroutine();
+        });
+
     setContentView(binding.getRoot());
   }