feat(replay): Record segment names (transaction names) (#5763)

* feat(replay): Record segment names

Co-Authored-By: Gino Buenaflor <giancarlo.buenaflor@sentry.io>

* docs: Add replay segment names changelog entry

* Format code

* test(replay): Use realistic Android transaction name

Co-Authored-By: Gino Buenaflor <giancarlo.buenaflor@sentry.io>

* build: Update replay API dumps

* test(replay): Use realistic Android segment names

Co-Authored-By: Gino Buenaflor <giancarlo.buenaflor@sentry.io>

* Format code

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com>
Co-authored-by: Gino Buenaflor <giancarlo.buenaflor@sentry.io>
Co-authored-by: Sentry Github Bot <bot+github-bot@sentry.io>
Co-authored-by: Giancarlo Buenaflor <giancarlo_buenaflor@yahoo.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: 4 people

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Features
 
+- Session Replay: Record segment names (transaction names) ([#5763](https://github.com/getsentry/sentry-java/pull/5763))
+
 - Add `io.sentry:sentry-opentelemetry-bom` to align Sentry OpenTelemetry modules with tested OpenTelemetry dependencies ([#5629](https://github.com/getsentry/sentry-java/pull/5629))
   - Spring Boot Gradle plugin: add the Sentry BOM to `dependencyManagement`; explicit imports are applied after Spring Boot's implicit BOM
     ```kotlin

sentry-android-replay/api/sentry-android-replay.api

@@ -76,6 +76,7 @@ public final class io/sentry/android/replay/ReplayIntegration : io/sentry/IConne
 	public fun onWindowSizeChanged (II)V
 	public fun pause ()V
 	public fun register (Lio/sentry/IScopes;Lio/sentry/SentryOptions;)V
+	public fun registerSegmentName (Ljava/lang/String;)V
 	public fun registerTraceId (Lio/sentry/protocol/SentryId;)V
 	public fun resume ()V
 	public fun setBreadcrumbConverter (Lio/sentry/ReplayBreadcrumbConverter;)V

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

@@ -297,6 +297,13 @@ public class ReplayIntegration(
     captureStrategy?.registerTraceId(traceId)
   }
 
+  override fun registerSegmentName(segmentName: String) {
+    if (!isEnabled.get() || !isRecording()) {
+      return
+    }
+    captureStrategy?.registerSegmentName(segmentName)
+  }
+
   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

@@ -54,7 +54,7 @@ internal abstract class BaseCaptureStrategy(
   internal companion object {
     private const val TAG = "CaptureStrategy"
     // https://github.com/getsentry/sentry-javascript/blob/30eb68fff5077211c30c61ba74625e66ab514870/packages/replay-internal/src/coreHandlers/handleAfterSendEvent.ts#L41
-    private const val MAX_TRACE_IDS = 100
+    private const val MAX_CONTEXT_VALUES = 100
   }
 
   private val gestureConverter = ReplayGestureConverter(dateProvider)
@@ -97,8 +97,9 @@ internal abstract class BaseCaptureStrategy(
     persistableAtomic(initialValue = false, propertyName = SEGMENT_KEY_FLUSHED)
 
   protected val currentEvents: Deque<RRWebEvent> = ConcurrentLinkedDeque()
-  private val traceIdsLock = Any()
-  private val currentTraceIds: MutableList<String> = mutableListOf()
+  private val replayContextLock = Any()
+  private val currentTraceIds: MutableSet<String> = linkedSetOf()
+  private val currentSegmentNames: MutableSet<String> = linkedSetOf()
 
   override fun start(segmentId: Int, replayId: SentryId, replayType: ReplayType?) {
     cache = replayCacheProvider?.invoke(replayId) ?: ReplayCache(options, replayId)
@@ -139,11 +140,12 @@ internal abstract class BaseCaptureStrategy(
     breadcrumbs: List<Breadcrumb>? = null,
     events: Deque<RRWebEvent> = this.currentEvents,
   ): ReplaySegment {
-    val traceIds =
-      synchronized(traceIdsLock) {
-        val ids = currentTraceIds.toList()
+    val (traceIds, segmentNames) =
+      synchronized(replayContextLock) {
+        val context = currentTraceIds.toList() to currentSegmentNames.toList()
         currentTraceIds.clear()
-        ids
+        currentSegmentNames.clear()
+        context
       }
     return createSegment(
       scopes,
@@ -162,6 +164,7 @@ internal abstract class BaseCaptureStrategy(
       breadcrumbs,
       events,
       traceIds,
+      segmentNames,
     )
   }
 
@@ -180,12 +183,19 @@ internal abstract class BaseCaptureStrategy(
 
   override fun registerTraceId(traceId: SentryId) {
     if (traceId != SentryId.EMPTY_ID) {
-      synchronized(traceIdsLock) {
-        if (currentTraceIds.size < MAX_TRACE_IDS) {
-          val id = traceId.toString()
-          if (!currentTraceIds.contains(id)) {
-            currentTraceIds.add(id)
-          }
+      synchronized(replayContextLock) {
+        if (currentTraceIds.size < MAX_CONTEXT_VALUES) {
+          currentTraceIds.add(traceId.toString())
+        }
+      }
+    }
+  }
+
+  override fun registerSegmentName(segmentName: String) {
+    if (segmentName.isNotEmpty()) {
+      synchronized(replayContextLock) {
+        if (currentSegmentNames.size < MAX_CONTEXT_VALUES) {
+          currentSegmentNames.add(segmentName)
         }
       }
     }

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

@@ -56,6 +56,8 @@ internal interface CaptureStrategy {
 
   fun registerTraceId(traceId: SentryId)
 
+  fun registerSegmentName(segmentName: String)
+
   companion object {
     private fun Breadcrumb?.isNetworkAvailable(): Boolean =
       this != null &&
@@ -88,6 +90,7 @@ internal interface CaptureStrategy {
       breadcrumbs: List<Breadcrumb>?,
       events: Deque<RRWebEvent>,
       traceIds: List<String> = emptyList(),
+      segmentNames: List<String> = emptyList(),
     ): ReplaySegment {
       val generatedVideo =
         cache?.createVideoOf(
@@ -127,6 +130,7 @@ internal interface CaptureStrategy {
         replayBreadcrumbs,
         events,
         traceIds,
+        segmentNames,
       )
     }
 
@@ -147,6 +151,7 @@ internal interface CaptureStrategy {
       breadcrumbs: List<Breadcrumb>,
       events: Deque<RRWebEvent>,
       traceIds: List<String>,
+      segmentNames: List<String>,
     ): ReplaySegment {
       val endTimestamp = DateUtils.getDateTime(segmentTimestamp.time + videoDuration)
       val replay =
@@ -159,6 +164,7 @@ internal interface CaptureStrategy {
           this.replayType = replayType
           this.videoFile = video
           this.traceIds = traceIds
+          this.segmentNames = segmentNames
         }
 
       val recordingPayload = mutableListOf<RRWebEvent>()

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

@@ -562,4 +562,58 @@ class SessionCaptureStrategyTest {
         any(),
       )
   }
+
+  @Test
+  fun `registerSegmentName includes unique segment names in next segment and clears them`() {
+    val now =
+      System.currentTimeMillis() + (fixture.options.sessionReplay.sessionSegmentDuration * 5)
+    val strategy = fixture.getSut(dateProvider = { now })
+    strategy.start()
+    strategy.onConfigurationChanged(fixture.recorderConfig)
+
+    strategy.registerSegmentName("CheckoutActivity")
+    strategy.registerSegmentName("CheckoutActivity")
+    strategy.registerSegmentName("ProductDetailsActivity")
+
+    strategy.onScreenshotRecorded(mock<Bitmap>()) {}
+
+    verify(fixture.scopes)
+      .captureReplay(
+        argThat { event ->
+          event is SentryReplayEvent &&
+            event.segmentNames == listOf("CheckoutActivity", "ProductDetailsActivity")
+        },
+        any(),
+      )
+
+    strategy.onScreenshotRecorded(mock<Bitmap>()) {}
+
+    verify(fixture.scopes)
+      .captureReplay(
+        argThat { event ->
+          event is SentryReplayEvent && event.segmentId == 1 && event.segmentNames.isNullOrEmpty()
+        },
+        any(),
+      )
+  }
+
+  @Test
+  fun `registerSegmentName ignores empty names and limits names to 100`() {
+    val now =
+      System.currentTimeMillis() + (fixture.options.sessionReplay.sessionSegmentDuration * 5)
+    val strategy = fixture.getSut(dateProvider = { now })
+    strategy.start()
+    strategy.onConfigurationChanged(fixture.recorderConfig)
+
+    strategy.registerSegmentName("")
+    repeat(101) { strategy.registerSegmentName("ProductActivity$it") }
+
+    strategy.onScreenshotRecorded(mock<Bitmap>()) {}
+
+    verify(fixture.scopes)
+      .captureReplay(
+        argThat { event -> event is SentryReplayEvent && event.segmentNames?.size == 100 },
+        any(),
+      )
+  }
 }

sentry/api/sentry.api

@@ -1715,6 +1715,7 @@ public final class io/sentry/NoOpReplayController : io/sentry/ReplayController {
 	public fun isDebugMaskingOverlayEnabled ()Z
 	public fun isRecording ()Z
 	public fun pause ()V
+	public fun registerSegmentName (Ljava/lang/String;)V
 	public fun registerTraceId (Lio/sentry/protocol/SentryId;)V
 	public fun resume ()V
 	public fun setBreadcrumbConverter (Lio/sentry/ReplayBreadcrumbConverter;)V
@@ -2357,6 +2358,7 @@ public abstract interface class io/sentry/ReplayController : io/sentry/IReplayAp
 	public abstract fun isDebugMaskingOverlayEnabled ()Z
 	public abstract fun isRecording ()Z
 	public abstract fun pause ()V
+	public abstract fun registerSegmentName (Ljava/lang/String;)V
 	public abstract fun registerTraceId (Lio/sentry/protocol/SentryId;)V
 	public abstract fun resume ()V
 	public abstract fun setBreadcrumbConverter (Lio/sentry/ReplayBreadcrumbConverter;)V
@@ -4023,6 +4025,7 @@ public final class io/sentry/SentryReplayEvent : io/sentry/SentryBaseEvent, io/s
 	public fun getReplayStartTimestamp ()Ljava/util/Date;
 	public fun getReplayType ()Lio/sentry/SentryReplayEvent$ReplayType;
 	public fun getSegmentId ()I
+	public fun getSegmentNames ()Ljava/util/List;
 	public fun getTimestamp ()Ljava/util/Date;
 	public fun getTraceIds ()Ljava/util/List;
 	public fun getType ()Ljava/lang/String;
@@ -4036,6 +4039,7 @@ public final class io/sentry/SentryReplayEvent : io/sentry/SentryBaseEvent, io/s
 	public fun setReplayStartTimestamp (Ljava/util/Date;)V
 	public fun setReplayType (Lio/sentry/SentryReplayEvent$ReplayType;)V
 	public fun setSegmentId (I)V
+	public fun setSegmentNames (Ljava/util/List;)V
 	public fun setTimestamp (Ljava/util/Date;)V
 	public fun setTraceIds (Ljava/util/List;)V
 	public fun setType (Ljava/lang/String;)V
@@ -4056,6 +4060,7 @@ public final class io/sentry/SentryReplayEvent$JsonKeys {
 	public static final field REPLAY_START_TIMESTAMP Ljava/lang/String;
 	public static final field REPLAY_TYPE Ljava/lang/String;
 	public static final field SEGMENT_ID Ljava/lang/String;
+	public static final field SEGMENT_NAMES Ljava/lang/String;
 	public static final field TIMESTAMP Ljava/lang/String;
 	public static final field TRACE_IDS Ljava/lang/String;
 	public static final field TYPE Ljava/lang/String;

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

@@ -60,4 +60,7 @@ public void disableDebugMaskingOverlay() {}
 
   @Override
   public void registerTraceId(@NotNull SentryId traceId) {}
+
+  @Override
+  public void registerSegmentName(@NotNull String segmentName) {}
 }

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

@@ -36,4 +36,7 @@ public interface ReplayController extends IReplayApi {
    * @param traceId the trace ID to associate with the current replay
    */
   void registerTraceId(@NotNull SentryId traceId);
+
+  /** Registers a segment name to be associated with the current replay segment. */
+  void registerSegmentName(@NotNull String segmentName);
 }

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

@@ -1079,6 +1079,10 @@ public void captureSession(final @NotNull Session session, final @Nullable Hint
       if (trace != null) {
         options.getReplayController().registerTraceId(trace.getTraceId());
       }
+      final @Nullable String segmentName = transaction.getTransaction();
+      if (segmentName != null && !segmentName.isEmpty()) {
+        options.getReplayController().registerSegmentName(segmentName);
+      }
     }
 
     return sentryId;