feat(compose): Introduce LocalSentrySpan (#6112)

Commit:

 1. Defines a LocalSentrySpan that lets Sentry and host apps deliver ISpan instances throughout composable subtrees. The delivered span can be used to parent any spans the receiving subtree produces, thereby freeing child composables from having to care about the ISpan hierarchies constructed by their ancestors.

 2. Introduces an internal UnsetSentrySpan + bootstrapping system that lets existing Sentry composable infrastructure provide its own ISpan in situations where the environment doesn't set a LocalSentrySpan.

 3. Updates SentryTraced to use both LocalSentrySpan and the bootstrapping system.

---------

Co-authored-by: Tabish Ahmad <tabishahmad1@gmail.com>

Author: 0xadam-brown

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Features
+
+- Add `LocalSentrySpan` to `sentry-compose` so apps can provide a parent `ISpan` to a composable subtree and have nested `SentryTraced` spans attach to it ([#6112]https://github.com/getsentry/sentry-java/pull/6112)
+
 ### Fixes
 
 - Disable URL caching when reading `META-INF/MANIFEST.MF` files during version detection so that the SDK no longer keeps jar file handles open for the life of the process ([#6124](https://github.com/getsentry/sentry-java/pull/6124)

sentry-compose/api/android/sentry-compose.api

@@ -6,6 +6,10 @@ public final class io/sentry/compose/BuildConfig {
 	public fun <init> ()V
 }
 
+public final class io/sentry/compose/LocalSentrySpanKt {
+	public static final fun getLocalSentrySpan ()Landroidx/compose/runtime/ProvidableCompositionLocal;
+}
+
 public final class io/sentry/compose/SentryComposeHelperKt {
 	public static final fun boundsInWindow (Landroidx/compose/ui/layout/LayoutCoordinates;Landroidx/compose/ui/layout/LayoutCoordinates;)Landroidx/compose/ui/geometry/Rect;
 }

sentry-compose/src/androidMain/kotlin/io/sentry/compose/LocalSentrySpan.kt

@@ -0,0 +1,72 @@
+package io.sentry.compose
+
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.CompositionLocalProvider
+import androidx.compose.runtime.ProvidableCompositionLocal
+import androidx.compose.runtime.compositionLocalOf
+import androidx.compose.ui.ExperimentalComposeUiApi
+import io.sentry.ISpan
+import io.sentry.NoOpSpan
+import io.sentry.Sentry
+
+/**
+ * A [ProvidableCompositionLocal] for delivering [ISpan]s to composable subtrees. The delivered span
+ * should be used to parent any spans the receiving subtree produces.
+ *
+ * Lets child composables remain agnostic about the [ISpan] hierarchies constructed by their
+ * ancestors.
+ */
+@ExperimentalComposeUiApi
+public val LocalSentrySpan: ProvidableCompositionLocal<ISpan> = compositionLocalOf {
+  UnsetSentrySpan
+}
+
+/**
+ * A wrapper for any composable subtree that should be passed the provided [span] via
+ * [LocalSentrySpan].
+ *
+ * The span is [normalized][normalize].
+ */
+@OptIn(ExperimentalComposeUiApi::class)
+@Composable
+internal fun ProvideSentrySpan(span: ISpan?, content: @Composable () -> Unit) {
+  CompositionLocalProvider(LocalSentrySpan provides span.normalize()) {
+    content()
+  }
+}
+
+/**
+ * Returns the receiver as-is unless it's an [UnsetSentrySpan], in which case it returns the current
+ * transaction.
+ *
+ * `*Bootstrap` methods are for internal use only. They're designed for scenarios where
+ * [LocalSentrySpan] hasn't been set, but we want to provide a reasonable alternative or fall back
+ * to preexisting behavior.
+ */
+internal fun ISpan.orBootstrapCurrentTransaction(): ISpan =
+  if (this.isUnset()) {
+    Sentry.getCurrentScopes().transaction.normalize()
+  } else {
+    this
+  }
+
+/**
+ * A sentinel span indicating that [LocalSentrySpan] hasn't been set. For internal use only.
+ *
+ * Note: This must be a distinct type from [NoOpSpan] so that [isUnset] can determine whether
+ * `LocalSentrySpan` was set with a `NoOpSpan` or was never set at all.
+ *
+ * Our own implementations often need to make that distinction so they can fall back to a reasonable
+ * parent span if their environment doesn't provide one. We use a sentinel to avoid complicating our
+ * public API for a distinction irrelevant to host apps.
+ */
+private object UnsetSentrySpan : ISpan by NoOpSpan.getInstance()
+
+private fun ISpan.isUnset(): Boolean = this === UnsetSentrySpan
+
+private fun ISpan?.normalize(): ISpan =
+  when {
+    this === UnsetSentrySpan || this is NoOpSpan -> this
+    this == null || this.isFinished -> NoOpSpan.getInstance()
+    else -> this
+  }

sentry-compose/src/androidMain/kotlin/io/sentry/compose/SentryComposeTracing.kt

@@ -10,7 +10,6 @@ import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.drawWithContent
 import io.sentry.ISpan
 import io.sentry.Instrumenter
-import io.sentry.NoOpSpan
 import io.sentry.Sentry
 import io.sentry.SentryDate
 import io.sentry.SpanOptions
@@ -71,7 +70,7 @@ public fun SentryTraced(
 ) {
   val baseModifier = if (enableUserInteractionTracing) modifier.sentryTag(tag) else modifier
   val scopes = Sentry.getCurrentScopes()
-  val ownerSpan = scopes.transaction ?: NoOpSpan.getInstance()
+  val ownerSpan = LocalSentrySpan.current.orBootstrapCurrentTransaction()
 
   val alreadyComposed = remember(ownerSpan) { MutableRef(false) }
   val alreadyRendered = remember(ownerSpan) { MutableRef(false) }

sentry-compose/src/androidUnitTest/kotlin/io/sentry/compose/SentryTracedTest.kt

@@ -28,6 +28,7 @@ import androidx.test.ext.junit.runners.AndroidJUnit4
 import com.google.common.truth.Truth.assertThat
 import io.sentry.ISpan
 import io.sentry.ITransaction
+import io.sentry.NoOpSpan
 import io.sentry.Sentry
 import io.sentry.SentryOptions
 import io.sentry.TransactionOptions
@@ -75,7 +76,9 @@ class SentryTracedTest {
   fun `records a composition span for the initial composition`() {
     val tx = initSentryAndStartTransaction("tx")
 
-    rule.setContent { SentryTraced(tag = "product_info") { Box(Modifier.size(1.dp)) } }
+    rule.setContent {
+      ProvideSentrySpan(tx) { SentryTraced(tag = "product_info") { Box(Modifier.size(1.dp)) } }
+    }
     tx.waitForSpanCount(OP_COMPOSE, 1)
 
     assertThat(tx.countSpans(OP_PARENT_COMPOSITION)).isEqualTo(1)
@@ -88,7 +91,7 @@ class SentryTracedTest {
   }
 
   @Test
-  fun `falls back to the current transaction when no owner span is provided`() {
+  fun `falls back to the current transaction when no owner span is provided via LocalSentrySpan`() {
     val tx = initSentryAndStartTransaction("tx")
 
     rule.setContent { SentryTraced(tag = "product_info") { Box(Modifier.size(1.dp)) } }
@@ -112,12 +115,32 @@ class SentryTracedTest {
   }
 
   @Test
-  fun `renders content without spans when the current transaction is finished`() {
+  fun `renders content without spans when provided owner span is a no-op`() {
+    val tx = initSentryAndStartTransaction("tx")
+
+    rule.setContent {
+      ProvideSentrySpan(NoOpSpan.getInstance()) {
+        SentryTraced(tag = "product_info") { Box(Modifier.size(1.dp).testTag("content")) }
+      }
+    }
+    rule.waitForIdle()
+
+    rule.onNodeWithTag("content").assertExists()
+    assertThat(tx.countSpans(OP_PARENT_COMPOSITION)).isEqualTo(0)
+    assertThat(tx.countSpans(OP_COMPOSE)).isEqualTo(0)
+    assertThat(tx.countSpans(OP_PARENT_RENDER)).isEqualTo(0)
+    assertThat(tx.countSpans(OP_RENDER)).isEqualTo(0)
+  }
+
+  @Test
+  fun `renders content without spans when provided owner span is finished`() {
     val tx = initSentryAndStartTransaction("tx")
     rule.runOnUiThread { tx.finish() }
 
     rule.setContent {
-      SentryTraced(tag = "product_info") { Box(Modifier.size(1.dp).testTag("content")) }
+      ProvideSentrySpan(tx) {
+        SentryTraced(tag = "product_info") { Box(Modifier.size(1.dp).testTag("content")) }
+      }
     }
     rule.waitForIdle()
 
@@ -136,7 +159,9 @@ class SentryTracedTest {
       }
 
     rule.setContent {
-      SentryTraced(tag = "product_info") { Box(Modifier.size(1.dp).testTag("content")) }
+      ProvideSentrySpan(tx) {
+        SentryTraced(tag = "product_info") { Box(Modifier.size(1.dp).testTag("content")) }
+      }
     }
     rule.waitForIdle()
     drawContent()
@@ -153,9 +178,11 @@ class SentryTracedTest {
     val tx = initSentryAndStartTransaction("tx")
 
     rule.setContent {
-      Column {
-        SentryTraced(tag = "product_info") { Box(Modifier.size(1.dp)) }
-        SentryTraced(tag = "add_to_cart_button") { Box(Modifier.size(1.dp)) }
+      ProvideSentrySpan(tx) {
+        Column {
+          SentryTraced(tag = "product_info") { Box(Modifier.size(1.dp)) }
+          SentryTraced(tag = "add_to_cart_button") { Box(Modifier.size(1.dp)) }
+        }
       }
     }
 
@@ -170,9 +197,11 @@ class SentryTracedTest {
     val tx = initSentryAndStartTransaction("tx")
 
     rule.setContent {
-      Column {
-        SentryTraced(tag = "product_info") { Box(Modifier.size(1.dp)) }
-        SentryTraced(tag = "add_to_cart_button") { Box(Modifier.size(1.dp)) }
+      ProvideSentrySpan(tx) {
+        Column {
+          SentryTraced(tag = "product_info") { Box(Modifier.size(1.dp)) }
+          SentryTraced(tag = "add_to_cart_button") { Box(Modifier.size(1.dp)) }
+        }
       }
     }
     tx.waitForSpanCount(OP_COMPOSE, 2)
@@ -200,9 +229,11 @@ class SentryTracedTest {
     val tx = initSentryAndStartTransaction("tx")
 
     rule.setContent {
-      val currentStep = step
-      SentryTraced(tag = "product_info") {
-        Box(Modifier.size((currentStep + 1).dp).testTag("content-$currentStep"))
+      ProvideSentrySpan(tx) {
+        val currentStep = step
+        SentryTraced(tag = "product_info") {
+          Box(Modifier.size((currentStep + 1).dp).testTag("content-$currentStep"))
+        }
       }
     }
     tx.waitForSpanCount(OP_COMPOSE, 1)
@@ -230,15 +261,17 @@ class SentryTracedTest {
     val tx = initSentryAndStartTransaction("tx")
 
     rule.setContent {
-      val currentStep = step
-      SentryTraced(tag = "product_info") {
-        val state = remember {
-          rememberedInstanceCount++
-          Any()
+      ProvideSentrySpan(tx) {
+        val currentStep = step
+        SentryTraced(tag = "product_info") {
+          val state = remember {
+            rememberedInstanceCount++
+            Any()
+          }
+          DisposableEffect(Unit) { onDispose { disposeCount++ } }
+          rememberedState = state
+          Box(Modifier.size((currentStep + 1).dp).testTag("content-$currentStep"))
         }
-        DisposableEffect(Unit) { onDispose { disposeCount++ } }
-        rememberedState = state
-        Box(Modifier.size((currentStep + 1).dp).testTag("content-$currentStep"))
       }
     }
     tx.waitForSpanCount(OP_COMPOSE, 1)
@@ -260,18 +293,24 @@ class SentryTracedTest {
   @Test
   fun `starts recording once an owner span becomes available`() {
     var step by mutableStateOf(0)
+    var sentrySpan by mutableStateOf<ISpan>(NoOpSpan.getInstance())
 
     rule.runOnUiThread { Sentry.close() }
     rule.setContent {
-      val currentStep = step
-      key(currentStep) {
-        SentryTraced(tag = "late-transaction-$currentStep") { Box(Modifier.size(1.dp)) }
+      ProvideSentrySpan(sentrySpan) {
+        val currentStep = step
+        key(currentStep) {
+          SentryTraced(tag = "late-transaction-$currentStep") { Box(Modifier.size(1.dp)) }
+        }
       }
     }
     rule.waitForIdle()
 
     val tx = initSentryAndStartTransaction("tx")
-    rule.runOnIdle { step = 1 }
+    rule.runOnIdle {
+      sentrySpan = tx
+      step = 1
+    }
     rule.waitForIdle()
 
     tx.waitForSpanCount(OP_COMPOSE, 1)
@@ -284,11 +323,14 @@ class SentryTracedTest {
   fun `records spans under replacement owner after previous owner finishes`() {
     var step by mutableStateOf(0)
     val firstTx = initSentryAndStartTransaction("first-tx")
+    var sentrySpan by mutableStateOf<ISpan>(firstTx)
 
     rule.setContent {
-      val currentStep = step
-      key(currentStep) {
-        SentryTraced(tag = "transaction-$currentStep") { Box(Modifier.size(1.dp)) }
+      ProvideSentrySpan(sentrySpan) {
+        val currentStep = step
+        key(currentStep) {
+          SentryTraced(tag = "transaction-$currentStep") { Box(Modifier.size(1.dp)) }
+        }
       }
     }
     firstTx.waitForSpanCount(OP_COMPOSE, 1)
@@ -298,7 +340,10 @@ class SentryTracedTest {
       firstTx.finish()
       secondTx = startBoundTransaction("second-tx")
     }
-    rule.runOnIdle { step = 1 }
+    rule.runOnIdle {
+      sentrySpan = secondTx
+      step = 1
+    }
     rule.waitForIdle()
 
     secondTx.waitForSpanCount(OP_COMPOSE, 1)
@@ -310,13 +355,12 @@ class SentryTracedTest {
 
   @Test
   fun `records a new span group when the owner span changes for the same composable node`() {
-    var step by mutableStateOf(0)
     val firstTx = initSentryAndStartTransaction("first-tx")
+    var sentrySpan by mutableStateOf<ISpan>(firstTx)
 
     rule.setContent {
-      val currentStep = step
-      SentryTraced(tag = "transaction", modifier = Modifier.testTag("content-$currentStep")) {
-        Box(Modifier.size((currentStep + 1).dp))
+      ProvideSentrySpan(sentrySpan) {
+        SentryTraced(tag = "transaction") { Box(Modifier.size(1.dp)) }
       }
     }
     firstTx.waitForSpanCount(OP_COMPOSE, 1)
@@ -328,14 +372,13 @@ class SentryTracedTest {
       firstTx.finish()
       secondTx = startBoundTransaction("second-tx")
     }
-    rule.runOnIdle { step = 1 }
+    rule.runOnIdle { sentrySpan = secondTx }
     rule.waitForIdle()
 
     secondTx.waitForSpanCount(OP_COMPOSE, 1)
     drawContent()
     secondTx.waitForSpanCount(OP_RENDER, 1)
 
-    rule.onNodeWithTag("content-1").assertExists()
     assertThat(firstTx.countSpans(OP_PARENT_COMPOSITION)).isEqualTo(1)
     assertThat(firstTx.countSpans(OP_PARENT_RENDER)).isEqualTo(1)
     assertThat(secondTx.countSpans(OP_PARENT_COMPOSITION)).isEqualTo(1)
@@ -349,7 +392,9 @@ class SentryTracedTest {
     val tx = initSentryAndStartTransaction("tx")
 
     assertFailsWith<IllegalStateException> {
-      rule.setContent { SentryTraced(tag = "throws") { error("boom") } }
+      rule.setContent {
+        ProvideSentrySpan(tx) { SentryTraced(tag = "throws") { error("boom") } }
+      }
     }
 
     assertThat(tx.countSpans(OP_PARENT_COMPOSITION)).isEqualTo(0)