fix(replay): Populate trace_ids in replay events for trace search

When a transaction is captured while replay is recording, the trace ID
is now registered with the replay controller and included in the next
replay segment. This enables searching for replays by trace ID in the
Sentry UI.

Fixes #5346

Slack thread: https://sentry.slack.com/archives/CP4UUUF1S/p1779889727948439?thread_ts=1777385469.860819&cid=CP4UUUF1S

https://claude.ai/code/session_012wjHQtsEPzcrxSMCufxrDY

Author: claude

sentry-android-replay/src/main/java/io/sentry/android/replay/ReplayIntegration.kt

@@ -280,6 +280,13 @@ public class ReplayIntegration(
 
   override fun isDebugMaskingOverlayEnabled(): Boolean = debugMaskingEnabled
 
+  override fun registerTraceId(traceId: SentryId) {
+    if (!isEnabled.get() || !isRecording()) {
+      return
+    }
+    captureStrategy?.registerTraceId(traceId)
+  }
+
   private fun pauseInternal() {
     lifecycleLock.acquire().use {
       if (!isEnabled.get() || !lifecycle.isAllowed(PAUSED)) {

sentry-android-replay/src/main/java/io/sentry/android/replay/capture/BaseCaptureStrategy.kt

@@ -33,6 +33,7 @@ import io.sentry.transport.ICurrentDateProvider
 import java.io.File
 import java.util.Date
 import java.util.Deque
+import java.util.concurrent.ConcurrentHashMap
 import java.util.concurrent.ConcurrentLinkedDeque
 import java.util.concurrent.Executors
 import java.util.concurrent.ScheduledExecutorService
@@ -96,6 +97,7 @@ internal abstract class BaseCaptureStrategy(
   override var replayType by persistableAtomic<ReplayType>(propertyName = SEGMENT_KEY_REPLAY_TYPE)
 
   protected val currentEvents: Deque<RRWebEvent> = ConcurrentLinkedDeque()
+  protected val currentTraceIds: MutableSet<String> = ConcurrentHashMap.newKeySet()
 
   override fun start(segmentId: Int, replayId: SentryId, replayType: ReplayType?) {
     cache = replayCacheProvider?.invoke(replayId) ?: ReplayCache(options, replayId)
@@ -135,8 +137,10 @@ internal abstract class BaseCaptureStrategy(
     screenAtStart: String? = this.screenAtStart,
     breadcrumbs: List<Breadcrumb>? = null,
     events: Deque<RRWebEvent> = this.currentEvents,
-  ): ReplaySegment =
-    createSegment(
+  ): ReplaySegment {
+    val traceIds = currentTraceIds.toList().ifEmpty { null }
+    currentTraceIds.clear()
+    return createSegment(
       scopes,
       options,
       duration,
@@ -152,7 +156,9 @@ internal abstract class BaseCaptureStrategy(
       screenAtStart,
       breadcrumbs,
       events,
+      traceIds,
     )
+  }
 
   override fun onConfigurationChanged(recorderConfig: ScreenshotRecorderConfig) {
     this.recorderConfig = recorderConfig
@@ -167,6 +173,12 @@ internal abstract class BaseCaptureStrategy(
     }
   }
 
+  override fun registerTraceId(traceId: SentryId) {
+    if (traceId != SentryId.EMPTY_ID) {
+      currentTraceIds.add(traceId.toString())
+    }
+  }
+
   private class ReplayPersistingExecutorServiceThreadFactory : ThreadFactory {
     private var cnt = 0
 

sentry-android-replay/src/main/java/io/sentry/android/replay/capture/CaptureStrategy.kt

@@ -53,6 +53,8 @@ internal interface CaptureStrategy {
 
   fun convert(): CaptureStrategy
 
+  fun registerTraceId(traceId: SentryId)
+
   companion object {
     private fun Breadcrumb?.isNetworkAvailable(): Boolean =
       this != null &&
@@ -84,6 +86,7 @@ internal interface CaptureStrategy {
       screenAtStart: String?,
       breadcrumbs: List<Breadcrumb>?,
       events: Deque<RRWebEvent>,
+      traceIds: List<String>? = null,
     ): ReplaySegment {
       val generatedVideo =
         cache?.createVideoOf(
@@ -122,6 +125,7 @@ internal interface CaptureStrategy {
         screenAtStart,
         replayBreadcrumbs,
         events,
+        traceIds,
       )
     }
 
@@ -141,6 +145,7 @@ internal interface CaptureStrategy {
       screenAtStart: String?,
       breadcrumbs: List<Breadcrumb>,
       events: Deque<RRWebEvent>,
+      traceIds: List<String>?,
     ): ReplaySegment {
       val endTimestamp = DateUtils.getDateTime(segmentTimestamp.time + videoDuration)
       val replay =
@@ -152,6 +157,7 @@ internal interface CaptureStrategy {
           this.replayStartTimestamp = segmentTimestamp
           this.replayType = replayType
           this.videoFile = video
+          this.traceIds = traceIds
         }
 
       val recordingPayload = mutableListOf<RRWebEvent>()

sentry-android-replay/src/test/java/io/sentry/android/replay/ReplayIntegrationTest.kt

@@ -1072,6 +1072,38 @@ class ReplayIntegrationTest {
     verify(fixture.replayCache).addFrame(any<Bitmap>(), any(), anyOrNull())
   }
 
+  @Test
+  fun `registerTraceId does nothing when replay is not started`() {
+    val replay = fixture.getSut(context)
+
+    replay.register(fixture.scopes, fixture.options)
+    // Don't call start()
+
+    // Should not throw
+    replay.registerTraceId(SentryId())
+  }
+
+  @Test
+  fun `registerTraceId forwards to capture strategy when recording`() {
+    var traceIdRegistered: SentryId? = null
+    val captureStrategy =
+      mock<CaptureStrategy> {
+        on { currentReplayId }.thenReturn(SentryId())
+        doAnswer { traceIdRegistered = it.arguments[0] as SentryId }
+          .whenever(mock)
+          .registerTraceId(any())
+      }
+    val replay = fixture.getSut(context, replayCaptureStrategyProvider = { captureStrategy })
+
+    replay.register(fixture.scopes, fixture.options)
+    replay.start()
+
+    val traceId = SentryId()
+    replay.registerTraceId(traceId)
+
+    assertEquals(traceId, traceIdRegistered)
+  }
+
   private fun getSessionCaptureStrategy(options: SentryOptions): SessionCaptureStrategy =
     SessionCaptureStrategy(
       options,

sentry-android-replay/src/test/java/io/sentry/android/replay/capture/SessionCaptureStrategyTest.kt

@@ -475,4 +475,81 @@ class SessionCaptureStrategyTest {
         },
       )
   }
+
+  @Test
+  fun `registerTraceId includes trace IDs in next segment`() {
+    val now =
+      System.currentTimeMillis() + (fixture.options.sessionReplay.sessionSegmentDuration * 5)
+    val strategy = fixture.getSut(dateProvider = { now })
+    strategy.start()
+    strategy.onConfigurationChanged(fixture.recorderConfig)
+
+    val traceId1 = SentryId()
+    val traceId2 = SentryId()
+    strategy.registerTraceId(traceId1)
+    strategy.registerTraceId(traceId2)
+
+    strategy.onScreenshotRecorded(mock<Bitmap>()) {}
+
+    verify(fixture.scopes)
+      .captureReplay(
+        argThat { event ->
+          event is SentryReplayEvent &&
+            event.traceIds?.size == 2 &&
+            event.traceIds!!.contains(traceId1.toString()) &&
+            event.traceIds!!.contains(traceId2.toString())
+        },
+        any(),
+      )
+  }
+
+  @Test
+  fun `registerTraceId clears trace IDs after segment is created`() {
+    val now =
+      System.currentTimeMillis() + (fixture.options.sessionReplay.sessionSegmentDuration * 5)
+    val strategy = fixture.getSut(dateProvider = { now })
+    strategy.start()
+    strategy.onConfigurationChanged(fixture.recorderConfig)
+
+    val traceId = SentryId()
+    strategy.registerTraceId(traceId)
+
+    strategy.onScreenshotRecorded(mock<Bitmap>()) {}
+
+    verify(fixture.scopes)
+      .captureReplay(
+        argThat { event ->
+          event is SentryReplayEvent && event.traceIds?.contains(traceId.toString()) == true
+        },
+        any(),
+      )
+
+    // trigger another segment, trace IDs should be cleared
+    strategy.onScreenshotRecorded(mock<Bitmap>()) {}
+
+    verify(fixture.scopes)
+      .captureReplay(
+        argThat { event -> event is SentryReplayEvent && event.segmentId == 1 && event.traceIds.isNullOrEmpty() },
+        any(),
+      )
+  }
+
+  @Test
+  fun `registerTraceId ignores empty trace ID`() {
+    val now =
+      System.currentTimeMillis() + (fixture.options.sessionReplay.sessionSegmentDuration * 5)
+    val strategy = fixture.getSut(dateProvider = { now })
+    strategy.start()
+    strategy.onConfigurationChanged(fixture.recorderConfig)
+
+    strategy.registerTraceId(SentryId.EMPTY_ID)
+
+    strategy.onScreenshotRecorded(mock<Bitmap>()) {}
+
+    verify(fixture.scopes)
+      .captureReplay(
+        argThat { event -> event is SentryReplayEvent && event.traceIds.isNullOrEmpty() },
+        any(),
+      )
+  }
 }

sentry/src/main/java/io/sentry/NoOpReplayController.java

@@ -57,4 +57,7 @@ public void enableDebugMaskingOverlay() {}
 
   @Override
   public void disableDebugMaskingOverlay() {}
+
+  @Override
+  public void registerTraceId(@NotNull SentryId traceId) {}
 }

sentry/src/main/java/io/sentry/ReplayController.java

@@ -28,4 +28,12 @@ public interface ReplayController extends IReplayApi {
   ReplayBreadcrumbConverter getBreadcrumbConverter();
 
   boolean isDebugMaskingOverlayEnabled();
+
+  /**
+   * Registers a trace ID to be associated with the current replay. This is called when a
+   * transaction is captured while replay is recording, to enable searching for replays by trace ID.
+   *
+   * @param traceId the trace ID to associate with the current replay
+   */
+  void registerTraceId(@NotNull SentryId traceId);
 }

sentry/src/main/java/io/sentry/SentryClient.java

@@ -1043,6 +1043,13 @@ public void captureSession(final @NotNull Session session, final @Nullable Hint
       sentryId = SentryId.EMPTY_ID;
     }
 
+    if (!sentryId.equals(SentryId.EMPTY_ID)) {
+      final @Nullable SpanContext trace = transaction.getContexts().getTrace();
+      if (trace != null) {
+        options.getReplayController().registerTraceId(trace.getTraceId());
+      }
+    }
+
     return sentryId;
   }
 

sentry/src/test/java/io/sentry/SentryClientTest.kt

@@ -1958,6 +1958,23 @@ class SentryClientTest {
     assertEquals("abc", transaction.platform)
   }
 
+  @Test
+  fun `captureTransaction registers trace ID with replay controller`() {
+    var registeredTraceId: SentryId? = null
+    fixture.sentryOptions.setReplayController(
+      object : ReplayController by NoOpReplayController.getInstance() {
+        override fun registerTraceId(traceId: SentryId) {
+          registeredTraceId = traceId
+        }
+      }
+    )
+    val sut = fixture.getSut()
+    val sentryTracer = SentryTracer(TransactionContext("name", "op"), fixture.scopes)
+    val transaction = SentryTransaction(sentryTracer)
+    sut.captureTransaction(transaction, sentryTracer.traceContext())
+    assertEquals(sentryTracer.spanContext.traceId, registeredTraceId)
+  }
+
   @Test
   fun `when exception type is ignored, capturing event does not send it`() {
     fixture.sentryOptions.addIgnoredExceptionForType(IllegalStateException::class.java)