Merge pull request #2772 from DataDog/aforsythe/RUM-8875/external-refresh-rate

RUM-8875 Add `updateExternalRefreshRate` to internal RUM API

Author: awforsythe

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

@@ -165,6 +165,7 @@ enum com.datadog.android.rum.RumSessionType
 class com.datadog.android.rum._RumInternalProxy
   fun addLongTask(Long, String)
   fun updatePerformanceMetric(RumPerformanceMetric, Double)
+  fun updateExternalRefreshRate(Double)
   fun setInternalViewAttribute(String, Any?)
   fun setSyntheticsAttribute(String?, String?)
   fun enableJankStatsTracking(android.app.Activity)

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

@@ -248,6 +248,7 @@ public final class com/datadog/android/rum/_RumInternalProxy {
 	public final fun enableJankStatsTracking (Landroid/app/Activity;)V
 	public final fun setInternalViewAttribute (Ljava/lang/String;Ljava/lang/Object;)V
 	public final fun setSyntheticsAttribute (Ljava/lang/String;Ljava/lang/String;)V
+	public final fun updateExternalRefreshRate (D)V
 	public final fun updatePerformanceMetric (Lcom/datadog/android/rum/RumPerformanceMetric;D)V
 }
 

features/dd-sdk-android-rum/src/main/kotlin/com/datadog/android/rum/_RumInternalProxy.kt

@@ -45,6 +45,10 @@ class _RumInternalProxy internal constructor(private val rumMonitor: AdvancedRum
         rumMonitor.updatePerformanceMetric(metric, value)
     }
 
+    fun updateExternalRefreshRate(frameTimeSeconds: Double) {
+        rumMonitor.updateExternalRefreshRate(frameTimeSeconds)
+    }
+
     fun setInternalViewAttribute(key: String, value: Any?) {
         rumMonitor.setInternalViewAttribute(key, value)
     }

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

@@ -217,6 +217,11 @@ internal sealed class RumRawEvent {
         override val eventTime: Time = Time()
     ) : RumRawEvent()
 
+    internal data class UpdateExternalRefreshRate(
+        val frameTimeSeconds: Double,
+        override val eventTime: Time = Time()
+    ) : RumRawEvent()
+
     internal data class SetInternalViewAttribute(
         val key: String,
         val value: Any?,

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

@@ -380,7 +380,8 @@ internal class RumViewManagerScope(
             RumRawEvent.LongTaskSent::class.java,
             RumRawEvent.ResourceDropped::class.java,
             RumRawEvent.ResourceSent::class.java,
-            RumRawEvent.UpdatePerformanceMetric::class.java
+            RumRawEvent.UpdatePerformanceMetric::class.java,
+            RumRawEvent.UpdateExternalRefreshRate::class.java
         )
 
         internal const val RUM_BACKGROUND_VIEW_ID = "com.datadog.background.view"

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

@@ -152,6 +152,8 @@ internal open class RumViewScope(
 
     private val performanceMetrics: MutableMap<RumPerformanceMetric, VitalInfo> = mutableMapOf()
 
+    private var externalRefreshRateInfo: VitalInfo? = null
+
     // endregion
 
     init {
@@ -211,6 +213,7 @@ internal open class RumViewScope(
             is RumRawEvent.StopSession -> onStopSession(event, writer)
 
             is RumRawEvent.UpdatePerformanceMetric -> onUpdatePerformanceMetric(event)
+            is RumRawEvent.UpdateExternalRefreshRate -> onUpdateExternalRefreshRate(event)
             is RumRawEvent.AddViewLoadingTime -> onAddViewLoadingTime(event, writer)
 
             else -> delegateEventToChildren(event, writer)
@@ -647,6 +650,31 @@ internal open class RumViewScope(
         )
     }
 
+    private fun onUpdateExternalRefreshRate(
+        event: RumRawEvent.UpdateExternalRefreshRate
+    ) {
+        if (stopped) return
+
+        // Convert frame time (seconds) to refresh rate (Hz)
+        val refreshRateHz = if (event.frameTimeSeconds > 0) {
+            1.0 / event.frameTimeSeconds
+        } else {
+            return // Invalid frame time
+        }
+
+        val currentInfo = externalRefreshRateInfo ?: VitalInfo.EMPTY
+        val newSampleCount = currentInfo.sampleCount + 1
+
+        // Calculate incremental mean using the same algorithm as performance metrics
+        val meanValue = (refreshRateHz + (currentInfo.sampleCount * currentInfo.meanValue)) / newSampleCount
+        externalRefreshRateInfo = VitalInfo(
+            newSampleCount,
+            min(refreshRateHz, currentInfo.minValue),
+            max(refreshRateHz, currentInfo.maxValue),
+            meanValue
+        )
+    }
+
     @WorkerThread
     private fun onSetInternalViewAttribute(event: RumRawEvent.SetInternalViewAttribute) {
         if (stopped) return
@@ -917,7 +945,8 @@ internal open class RumViewScope(
 
         val timings = resolveCustomTimings()
         val memoryInfo = lastMemoryInfo
-        val refreshRateInfo = lastFrameRateInfo
+        // Use external refresh rate data if available, otherwise fall back to internal data
+        val refreshRateInfo = externalRefreshRateInfo ?: lastFrameRateInfo
         val isSlowRendered = resolveRefreshRateInfo(refreshRateInfo) ?: false
         // make a copy - by the time we iterate over it on another thread, it may already be changed
         val eventFeatureFlags = featureFlags.toMutableMap()

features/dd-sdk-android-rum/src/main/kotlin/com/datadog/android/rum/internal/monitor/AdvancedRumMonitor.kt

@@ -49,6 +49,8 @@ internal interface AdvancedRumMonitor : RumMonitor, AdvancedNetworkRumMonitor {
 
     fun updatePerformanceMetric(metric: RumPerformanceMetric, value: Double)
 
+    fun updateExternalRefreshRate(frameTimeSeconds: Double)
+
     fun setInternalViewAttribute(key: String, value: Any?)
 
     fun setSyntheticsAttribute(testId: String, resultId: String)

features/dd-sdk-android-rum/src/main/kotlin/com/datadog/android/rum/internal/monitor/DatadogRumMonitor.kt

@@ -634,6 +634,10 @@ internal class DatadogRumMonitor(
         handleEvent(RumRawEvent.UpdatePerformanceMetric(metric, value))
     }
 
+    override fun updateExternalRefreshRate(frameTimeSeconds: Double) {
+        handleEvent(RumRawEvent.UpdateExternalRefreshRate(frameTimeSeconds))
+    }
+
     override fun setInternalViewAttribute(key: String, value: Any?) {
         handleEvent(RumRawEvent.SetInternalViewAttribute(key, value))
     }

features/dd-sdk-android-rum/src/test/kotlin/com/datadog/android/rum/RumInternalProxyTest.kt

@@ -10,6 +10,7 @@ import android.app.Activity
 import com.datadog.android.rum.internal.monitor.AdvancedRumMonitor
 import com.datadog.android.rum.utils.forge.Configurator
 import fr.xgouchet.elmyr.Forge
+import fr.xgouchet.elmyr.annotation.DoubleForgery
 import fr.xgouchet.elmyr.annotation.LongForgery
 import fr.xgouchet.elmyr.annotation.StringForgery
 import fr.xgouchet.elmyr.junit5.ForgeConfiguration
@@ -64,6 +65,21 @@ internal class RumInternalProxyTest {
         verify(mockRumMonitor).updatePerformanceMetric(metric, value)
     }
 
+    @Test
+    fun `M proxy updateExternalRefreshRate to RumMonitor W updateExternalRefreshRate()`(
+        @DoubleForgery(min = 0.001, max = 1.0) frameTimeSeconds: Double
+    ) {
+        // Given
+        val mockRumMonitor = mock(AdvancedRumMonitor::class.java)
+        val proxy = _RumInternalProxy(mockRumMonitor)
+
+        // When
+        proxy.updateExternalRefreshRate(frameTimeSeconds)
+
+        // Then
+        verify(mockRumMonitor).updateExternalRefreshRate(frameTimeSeconds)
+    }
+
     @Test
     fun `M proxy enableJankStatsTracking to RumMonitor W enableJankStatsTracking()`() {
         // Given

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

@@ -150,6 +150,14 @@ internal fun Forge.updatePerformanceMetricEvent(): RumRawEvent.UpdatePerformance
     )
 }
 
+internal fun Forge.updateExternalRefreshRateEvent(): RumRawEvent.UpdateExternalRefreshRate {
+    val time = Time()
+    return RumRawEvent.UpdateExternalRefreshRate(
+        frameTimeSeconds = aDouble(),
+        eventTime = time
+    )
+}
+
 internal fun Forge.addFeatureFlagEvaluationEvent(): RumRawEvent.AddFeatureFlagEvaluation {
     val time = Time()
     return RumRawEvent.AddFeatureFlagEvaluation(
@@ -206,6 +214,7 @@ internal fun Forge.anyRumEvent(excluding: List<KClass<out RumRawEvent>> = listOf
         strictSameTypePair(RumRawEvent.AddFeatureFlagEvaluation::class, { addFeatureFlagEvaluationEvent() }),
         strictSameTypePair(RumRawEvent.AddCustomTiming::class, { addCustomTimingEvent() }),
         strictSameTypePair(RumRawEvent.UpdatePerformanceMetric::class, { updatePerformanceMetricEvent() }),
+        strictSameTypePair(RumRawEvent.UpdateExternalRefreshRate::class, { updateExternalRefreshRateEvent() }),
         strictSameTypePair(RumRawEvent.AddViewLoadingTime::class, { addViewLoadingTimeEvent() })
     )
     return this.anElementFrom(