RUM-15138: Rebase trace sample rate against RUM session sample rate for correlated cross-product sampling

DeterministicTraceSampler now applies a cross-product rebasing formula when a span carries a RUM session ID tag: rebasedRate = sessionSampleRate × traceSampleRate / 100. Previously, the raw traceSampleRate was used as the sampling threshold regardless of whether the session ID was the hash key, causing the effective trace rate among RUM-tracked sessions to be incorrect.

The session sample rate is propagated via RumContext (new sessionSampleRate field) into the SDK feature context, then written onto spans as a tag by RumContextPropagator alongside the existing RUM tags. DeterministicTraceSampler reads the tag at sampling time and applies the rebasing; spans without a session ID tag continue to use the raw trace rate unchanged.

RumSessionScope snapshots sessionSampleRate in renewSession() at the moment the sampling decision is made, ensuring the rate is immutable for the lifetime of that session.

Author: hamorillo

detekt_custom_safe_calls.yml

@@ -1126,6 +1126,7 @@ datadog:
       - "kotlin.Double.toInt()"
       - "kotlin.Double.toLong()"
       - "kotlin.Double.toULong()"
+      - "kotlin.Float.coerceAtMost(kotlin.Float)"
       - "kotlin.Float.fromBits(kotlin.Int)"
       - "kotlin.Float.percent()"
       - "kotlin.Float.roundToInt()"

features/dd-sdk-android-rum/src/main/kotlin/com/datadog/android/rum/internal/domain/RumContext.kt

@@ -25,7 +25,8 @@ internal data class RumContext(
     val syntheticsResultId: String? = null,
     val viewTimestamp: Long = 0L,
     val viewTimestampOffset: Long = 0L,
-    val hasReplay: Boolean = false
+    val hasReplay: Boolean = false,
+    val sessionSampleRate: Float = FULL_SESSION_SAMPLE_RATE
 ) {
 
     fun toMap(): Map<String, Any?> {
@@ -44,7 +45,8 @@ internal data class RumContext(
             SYNTHETICS_RESULT_ID to syntheticsResultId,
             VIEW_TIMESTAMP to viewTimestamp,
             HAS_REPLAY to hasReplay,
-            VIEW_TIMESTAMP_OFFSET to viewTimestampOffset
+            VIEW_TIMESTAMP_OFFSET to viewTimestampOffset,
+            SESSION_SAMPLE_RATE to sessionSampleRate
         )
     }
 
@@ -68,6 +70,8 @@ internal data class RumContext(
         const val HAS_REPLAY = "view_has_replay"
         const val VIEW_TIMESTAMP = "view_timestamp"
         const val VIEW_TIMESTAMP_OFFSET = "view_timestamp_offset"
+        const val SESSION_SAMPLE_RATE = "session_sample_rate"
+        const val FULL_SESSION_SAMPLE_RATE: Float = 100f
 
         fun fromFeatureContext(featureContext: Map<String, Any?>): RumContext {
             val applicationId = featureContext[APPLICATION_ID] as? String
@@ -89,6 +93,8 @@ internal data class RumContext(
             val hasReplay = featureContext[HAS_REPLAY] as? Boolean ?: false
             val viewTimestamp = featureContext[VIEW_TIMESTAMP] as? Long ?: 0L
             val viewTimestampOffset = featureContext[VIEW_TIMESTAMP_OFFSET] as? Long ?: 0L
+            val sessionSampleRate = (featureContext[SESSION_SAMPLE_RATE] as? Number)
+                ?.toFloat() ?: FULL_SESSION_SAMPLE_RATE
 
             return RumContext(
                 applicationId = applicationId ?: NULL_UUID,
@@ -105,7 +111,8 @@ internal data class RumContext(
                 syntheticsResultId = syntheticsResultId,
                 viewTimestamp = viewTimestamp,
                 viewTimestampOffset = viewTimestampOffset,
-                hasReplay = hasReplay
+                hasReplay = hasReplay,
+                sessionSampleRate = sessionSampleRate
             )
         }
     }

features/dd-sdk-android-rum/src/main/kotlin/com/datadog/android/rum/internal/domain/scope/RumSessionScope.kt

@@ -65,6 +65,7 @@ internal class RumSessionScope(
 
     internal var sessionId = RumContext.NULL_UUID
     internal var sessionState: State = State.NOT_TRACKED
+    internal var sessionSampleRate: Float = sessionSampler.getSampleRate() ?: RumContext.FULL_SESSION_SAMPLE_RATE
     private var startReason: StartReason = StartReason.USER_APP_LAUNCH
     internal var isActive: Boolean = true
     private val sessionStartNs = AtomicLong(sdkCore.timeProvider.getDeviceElapsedTimeNanos())
@@ -211,7 +212,8 @@ internal class RumSessionScope(
             sessionId = sessionId,
             sessionState = sessionState,
             sessionStartReason = startReason,
-            isSessionActive = isActive
+            isSessionActive = isActive,
+            sessionSampleRate = sessionSampleRate
         )
     }
 
@@ -280,6 +282,7 @@ internal class RumSessionScope(
 
     private fun renewSession(time: Time, reason: StartReason) {
         val newSessionId = UUID.randomUUID().toString()
+        sessionSampleRate = sessionSampler.getSampleRate() ?: RumContext.FULL_SESSION_SAMPLE_RATE
         val keepSession = sessionSampler.sample(newSessionId)
         startReason = reason
         sessionState = if (keepSession) State.TRACKED else State.NOT_TRACKED

features/dd-sdk-android-rum/src/test/kotlin/com/datadog/android/rum/internal/domain/RumContextTest.kt

@@ -12,6 +12,7 @@ import fr.xgouchet.elmyr.junit5.ForgeConfiguration
 import fr.xgouchet.elmyr.junit5.ForgeExtension
 import org.assertj.core.api.Assertions.assertThat
 import org.junit.jupiter.api.RepeatedTest
+import org.junit.jupiter.api.Test
 import org.junit.jupiter.api.extension.ExtendWith
 
 @ExtendWith(ForgeExtension::class)
@@ -28,4 +29,18 @@ internal class RumContextTest {
         // Then
         assertThat(anotherRumContext).isEqualTo(fakeRumContext)
     }
+
+    @Test
+    fun `M parse session sample rate W fromFeatureContext() {value is Double}`() {
+        // Given
+        val featureContext = mapOf<String, Any?>(
+            RumContext.SESSION_SAMPLE_RATE to 42.5
+        )
+
+        // When
+        val rumContext = RumContext.fromFeatureContext(featureContext)
+
+        // Then
+        assertThat(rumContext.sessionSampleRate).isEqualTo(42.5f)
+    }
 }

features/dd-sdk-android-rum/src/test/kotlin/com/datadog/android/rum/internal/domain/scope/RumSessionScopeTest.kt

@@ -266,6 +266,16 @@ internal class RumSessionScopeTest {
         assertThat(childScope?.sampleRate).isCloseTo(fakeSampleRate, offset(0.001f))
     }
 
+    @Test
+    fun `M use full session sample rate W init() { getSampleRate returns null }`() {
+        // Given
+        whenever(mockSessionSampler.getSampleRate()).thenReturn(null)
+        initializeTestedScope(withMockChildScope = false)
+
+        // Then
+        assertThat(testedScope.sessionSampleRate).isEqualTo(RumContext.FULL_SESSION_SAMPLE_RATE)
+    }
+
     @Test
     fun `M delegate events to child scope W handleViewEvent() {TRACKED}`(
         forge: Forge
@@ -478,6 +488,43 @@ internal class RumSessionScopeTest {
         assertThat(context.viewId).isEqualTo(fakeParentContext.viewId)
     }
 
+    @Test
+    fun `M keep session sample rate stable W getRumContext() {sampler rate changes mid-session}`(
+        forge: Forge
+    ) {
+        // Given
+        whenever(mockSessionSampler.getSampleRate()).thenReturn(100f, 20f)
+        whenever(mockSessionSampler.sample(any())).thenReturn(true)
+        initializeTestedScope()
+
+        // When
+        testedScope.handleEvent(forge.startViewEvent(), fakeDatadogContext, mockEventWriteScope, mockWriter)
+        val firstContext = testedScope.getRumContext()
+        whenever(mockSessionSampler.getSampleRate()).thenReturn(100f)
+        val secondContext = testedScope.getRumContext()
+
+        // Then
+        assertThat(firstContext.sessionSampleRate).isEqualTo(20f)
+        assertThat(secondContext.sessionSampleRate).isEqualTo(20f)
+    }
+
+    @Test
+    fun `M use full session sample rate W getRumContext() {getSampleRate returns null on renewSession}`(
+        forge: Forge
+    ) {
+        // Given
+        whenever(mockSessionSampler.getSampleRate()).thenReturn(null)
+        whenever(mockSessionSampler.sample(any())).thenReturn(true)
+        initializeTestedScope()
+
+        // When
+        testedScope.handleEvent(forge.startViewEvent(), fakeDatadogContext, mockEventWriteScope, mockWriter)
+        val context = testedScope.getRumContext()
+
+        // Then
+        assertThat(context.sessionSampleRate).isEqualTo(RumContext.FULL_SESSION_SAMPLE_RATE)
+    }
+
     @Test
     fun `M set TRACKED W renewSession() {sampler returns true}`(forge: Forge) {
         // Given

features/dd-sdk-android-trace/api/apiSurface

@@ -22,6 +22,7 @@ open class com.datadog.android.trace.DeterministicTraceSampler : com.datadog.and
   constructor(() -> Float)
   constructor(Float)
   constructor(Double)
+  override fun sample(com.datadog.android.trace.api.span.DatadogSpan): Boolean
 annotation com.datadog.android.trace.ExperimentalTraceApi
 object com.datadog.android.trace.GlobalDatadogTracer
   fun registerIfAbsent(com.datadog.android.trace.api.tracer.DatadogTracer): Boolean

features/dd-sdk-android-trace/api/dd-sdk-android-trace.api

@@ -32,6 +32,8 @@ public class com/datadog/android/trace/DeterministicTraceSampler : com/datadog/a
 	public fun <init> (D)V
 	public fun <init> (F)V
 	public fun <init> (Lkotlin/jvm/functions/Function0;)V
+	public fun sample (Lcom/datadog/android/trace/api/span/DatadogSpan;)Z
+	public synthetic fun sample (Ljava/lang/Object;)Z
 }
 
 public abstract interface annotation class com/datadog/android/trace/ExperimentalTraceApi : java/lang/annotation/Annotation {

features/dd-sdk-android-trace/src/main/kotlin/com/datadog/android/trace/DeterministicTraceSampler.kt

@@ -8,12 +8,23 @@ package com.datadog.android.trace
 
 import androidx.annotation.FloatRange
 import com.datadog.android.core.sampling.DeterministicSampler
+import com.datadog.android.log.LogAttributes
 import com.datadog.android.trace.api.span.DatadogSpan
+import com.datadog.android.trace.internal.RumContextPropagator
 import com.datadog.android.trace.internal.net.SpanSamplingIdProvider
 
 /**
  * A [com.datadog.android.core.sampling.DeterministicSampler] using the TraceID of a Span to compute the sampling decision.
  *
+ * When a span is linked to an active RUM session (i.e. the span carries a `rum.session.id` tag),
+ * the sampling threshold is automatically rebased against the RUM session sample rate so that
+ * the combined effective sampling probability reflects the configured trace sample rate applied
+ * only to the sessions already tracked by RUM:
+ *
+ * ```
+ * rebasedTraceSampleRate = sessionSampleRate * traceSampleRate / 100
+ * ```
+ *
  * @param sampleRateProvider Provider for the sample rate value which will be called each time
  * the sampling decision needs to be made. All the values should be in the range [0;100].
  */
@@ -41,4 +52,33 @@ open class DeterministicTraceSampler(
     constructor(
         @FloatRange(from = 0.0, to = 100.0) sampleRate: Double
     ) : this(sampleRate.toFloat())
+
+    /** @inheritDoc */
+    override fun sample(item: DatadogSpan): Boolean {
+        val sampleRate = rebasedSampleRate(item)
+        return when {
+            sampleRate >= DeterministicSampler.SAMPLE_ALL_RATE -> true
+            sampleRate <= 0f -> false
+            else -> {
+                val hash = SpanSamplingIdProvider.provideId(item) * DeterministicSampler.SAMPLER_HASHER
+                val threshold = (
+                    DeterministicSampler.MAX_ID.toDouble() * sampleRate / DeterministicSampler.SAMPLE_ALL_RATE
+                    ).toULong()
+                hash < threshold
+            }
+        }
+    }
+
+    private fun rebasedSampleRate(item: DatadogSpan): Float {
+        val traceSampleRate = getSampleRate()
+        val sessionId = item.context().tags[LogAttributes.RUM_SESSION_ID] as? String
+        val sessionSampleRate = item.context().tags[RumContextPropagator.SESSION_SAMPLE_RATE_KEY] as? Number
+
+        return if (sessionId != null && sessionSampleRate != null) {
+            (traceSampleRate * sessionSampleRate.toFloat() / DeterministicSampler.SAMPLE_ALL_RATE)
+                .coerceAtMost(DeterministicSampler.SAMPLE_ALL_RATE)
+        } else {
+            traceSampleRate
+        }
+    }
 }

features/dd-sdk-android-trace/src/main/kotlin/com/datadog/android/trace/internal/RumContextPropagator.kt

@@ -62,6 +62,7 @@ class RumContextPropagator(private val sdkCoreProvider: () -> FeatureSdkCore?) {
                 instance.setTag(LogAttributes.RUM_SESSION_ID, rumContext["session_id"])
                 instance.setTag(LogAttributes.RUM_VIEW_ID, rumContext["view_id"])
                 instance.setTag(LogAttributes.RUM_ACTION_ID, rumContext["action_id"])
+                instance.setTag(SESSION_SAMPLE_RATE_KEY, rumContext[SESSION_SAMPLE_RATE_KEY])
                 instance.setTag(HttpCodec.RUM_KEY_USER_ID, datadogContext.userInfo.id)
                 instance.setTag(HttpCodec.RUM_KEY_ACCOUNT_ID, datadogContext.accountInfo?.id)
             }
@@ -109,6 +110,7 @@ class RumContextPropagator(private val sdkCoreProvider: () -> FeatureSdkCore?) {
 
     companion object {
         internal const val DATADOG_INITIAL_CONTEXT: String = "_dd.datadog_initial_context"
+        internal const val SESSION_SAMPLE_RATE_KEY: String = "session_sample_rate"
 
         internal const val INITIAL_DATADOG_CONTEXT_NOT_AVAILABLE_ERROR = "Initial span creation Datadog context" +
             " is not available at the write time."

features/dd-sdk-android-trace/src/test/kotlin/com/datadog/android/trace/internal/RumContextPropagatorTest.kt

@@ -24,6 +24,7 @@ import com.datadog.android.trace.internal.RumContextPropagator.Companion.injectR
 import com.datadog.android.trace.utils.RumContextTestsUtils.RUM_CONTEXT_ACTION_ID
 import com.datadog.android.trace.utils.RumContextTestsUtils.RUM_CONTEXT_APPLICATION_ID
 import com.datadog.android.trace.utils.RumContextTestsUtils.RUM_CONTEXT_SESSION_ID
+import com.datadog.android.trace.utils.RumContextTestsUtils.RUM_CONTEXT_SESSION_SAMPLE_RATE
 import com.datadog.android.trace.utils.RumContextTestsUtils.RUM_CONTEXT_VIEW_ID
 import com.datadog.android.trace.utils.RumContextTestsUtils.aDatadogContextWithRumContext
 import com.datadog.android.trace.utils.RumContextTestsUtils.aRumContext
@@ -293,6 +294,9 @@ class RumContextPropagatorTest {
         verify(span).setTag(LogAttributes.RUM_SESSION_ID, fakeRumContext[RUM_CONTEXT_SESSION_ID])
         verify(span).setTag(LogAttributes.RUM_VIEW_ID, fakeRumContext[RUM_CONTEXT_VIEW_ID])
         verify(span).setTag(LogAttributes.RUM_ACTION_ID, fakeRumContext[RUM_CONTEXT_ACTION_ID])
+        verify(
+            span
+        ).setTag(RumContextPropagator.SESSION_SAMPLE_RATE_KEY, fakeRumContext[RUM_CONTEXT_SESSION_SAMPLE_RATE])
         verify(span).setTag(HttpCodec.RUM_KEY_ACCOUNT_ID, fakeDatadogContext.accountInfo?.id as? Any)
         verify(span).setTag(HttpCodec.RUM_KEY_USER_ID, fakeDatadogContext.userInfo.id as? Any)
         verify(span).setTag(DATADOG_INITIAL_CONTEXT, null as Any?)
@@ -317,6 +321,9 @@ class RumContextPropagatorTest {
         verify(span).setTag(LogAttributes.RUM_SESSION_ID, fakeRumContext[RUM_CONTEXT_SESSION_ID])
         verify(span).setTag(LogAttributes.RUM_VIEW_ID, fakeRumContext[RUM_CONTEXT_VIEW_ID])
         verify(span).setTag(LogAttributes.RUM_ACTION_ID, fakeRumContext[RUM_CONTEXT_ACTION_ID])
+        verify(
+            span
+        ).setTag(RumContextPropagator.SESSION_SAMPLE_RATE_KEY, fakeRumContext[RUM_CONTEXT_SESSION_SAMPLE_RATE])
         verify(span).setTag(HttpCodec.RUM_KEY_ACCOUNT_ID, fakeDatadogContext.accountInfo?.id as? Any)
         verify(span).setTag(HttpCodec.RUM_KEY_USER_ID, fakeDatadogContext.userInfo.id as? Any)
         verify(span).setTag(DATADOG_INITIAL_CONTEXT, null as Any?)
@@ -339,6 +346,7 @@ class RumContextPropagatorTest {
         verify(span).setTag(LogAttributes.RUM_SESSION_ID, null as Any?)
         verify(span).setTag(LogAttributes.RUM_VIEW_ID, null as Any?)
         verify(span).setTag(LogAttributes.RUM_ACTION_ID, null as Any?)
+        verify(span).setTag(RumContextPropagator.SESSION_SAMPLE_RATE_KEY, null as Any?)
         verify(span).setTag(HttpCodec.RUM_KEY_ACCOUNT_ID, null as Any?)
         verify(span).setTag(HttpCodec.RUM_KEY_USER_ID, null as Any?)
         verify(span).setTag(DATADOG_INITIAL_CONTEXT, null as Any?)
@@ -362,6 +370,7 @@ class RumContextPropagatorTest {
         verify(span).setTag(LogAttributes.RUM_SESSION_ID, null as Any?)
         verify(span).setTag(LogAttributes.RUM_VIEW_ID, null as Any?)
         verify(span).setTag(LogAttributes.RUM_ACTION_ID, null as Any?)
+        verify(span).setTag(RumContextPropagator.SESSION_SAMPLE_RATE_KEY, null as Any?)
         verify(span).setTag(HttpCodec.RUM_KEY_ACCOUNT_ID, null as Any?)
         verify(span).setTag(HttpCodec.RUM_KEY_USER_ID, null as Any?)
         verify(span).setTag(DATADOG_INITIAL_CONTEXT, null as Any?)