Merge pull request #2541 from DataDog/tvaleev/RUM-8947/configuration_support

[RUM-8947] - configuration support

Author: satween

Diff for: features/dd-sdk-android-rum/api/apiSurface

@@ -86,6 +86,7 @@ data class com.datadog.android.rum.RumConfiguration
     fun setSessionListener(RumSessionListener): Builder
     fun setInitialResourceIdentifier(com.datadog.android.rum.metric.networksettled.InitialResourceIdentifier): Builder
     fun setLastInteractionIdentifier(com.datadog.android.rum.metric.interactiontonextview.LastInteractionIdentifier?): Builder
+    fun setSlowFrameListenerConfiguration(com.datadog.android.rum.configuration.SlowFrameListenerConfiguration?): Builder
     fun build(): RumConfiguration
 enum com.datadog.android.rum.RumErrorSource
   - NETWORK
@@ -164,6 +165,10 @@ class com.datadog.android.rum._RumInternalProxy
   companion object 
     fun setTelemetryConfigurationEventMapper(RumConfiguration.Builder, com.datadog.android.event.EventMapper<com.datadog.android.telemetry.model.TelemetryConfigurationEvent>): RumConfiguration.Builder
     fun setAdditionalConfiguration(RumConfiguration.Builder, Map<String, Any>): RumConfiguration.Builder
+data class com.datadog.android.rum.configuration.SlowFrameListenerConfiguration
+  constructor(Int = DEFAULT_SLOW_FRAME_RECORDS_MAX_AMOUNT, Long = DEFAULT_FROZEN_FRAME_THRESHOLD_NS, Long = DEFAULT_CONTINUOUS_SLOW_FRAME_THRESHOLD_NS, Long = DEFAULT_FREEZE_DURATION_NS, Long = DEFAULT_VIEW_LIFETIME_THRESHOLD_NS)
+  companion object 
+    val DEFAULT: SlowFrameListenerConfiguration
 enum com.datadog.android.rum.configuration.VitalsUpdateFrequency
   constructor(Long)
   - FREQUENT

Diff for: features/dd-sdk-android-rum/api/dd-sdk-android-rum.api

@@ -111,6 +111,7 @@ public final class com/datadog/android/rum/RumConfiguration$Builder {
 	public final fun setResourceEventMapper (Lcom/datadog/android/event/EventMapper;)Lcom/datadog/android/rum/RumConfiguration$Builder;
 	public final fun setSessionListener (Lcom/datadog/android/rum/RumSessionListener;)Lcom/datadog/android/rum/RumConfiguration$Builder;
 	public final fun setSessionSampleRate (F)Lcom/datadog/android/rum/RumConfiguration$Builder;
+	public final fun setSlowFrameListenerConfiguration (Lcom/datadog/android/rum/configuration/SlowFrameListenerConfiguration;)Lcom/datadog/android/rum/RumConfiguration$Builder;
 	public final fun setTelemetrySampleRate (F)Lcom/datadog/android/rum/RumConfiguration$Builder;
 	public final fun setViewEventMapper (Lcom/datadog/android/rum/event/ViewEventMapper;)Lcom/datadog/android/rum/RumConfiguration$Builder;
 	public final fun setVitalsUpdateFrequency (Lcom/datadog/android/rum/configuration/VitalsUpdateFrequency;)Lcom/datadog/android/rum/RumConfiguration$Builder;
@@ -245,6 +246,22 @@ public final class com/datadog/android/rum/_RumInternalProxy$Companion {
 	public final fun setTelemetryConfigurationEventMapper (Lcom/datadog/android/rum/RumConfiguration$Builder;Lcom/datadog/android/event/EventMapper;)Lcom/datadog/android/rum/RumConfiguration$Builder;
 }
 
+public final class com/datadog/android/rum/configuration/SlowFrameListenerConfiguration {
+	public static final field Companion Lcom/datadog/android/rum/configuration/SlowFrameListenerConfiguration$Companion;
+	public fun <init> ()V
+	public fun <init> (IJJJJ)V
+	public synthetic fun <init> (IJJJJILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public final fun copy (IJJJJ)Lcom/datadog/android/rum/configuration/SlowFrameListenerConfiguration;
+	public static synthetic fun copy$default (Lcom/datadog/android/rum/configuration/SlowFrameListenerConfiguration;IJJJJILjava/lang/Object;)Lcom/datadog/android/rum/configuration/SlowFrameListenerConfiguration;
+	public fun equals (Ljava/lang/Object;)Z
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class com/datadog/android/rum/configuration/SlowFrameListenerConfiguration$Companion {
+	public final fun getDEFAULT ()Lcom/datadog/android/rum/configuration/SlowFrameListenerConfiguration;
+}
+
 public final class com/datadog/android/rum/configuration/VitalsUpdateFrequency : java/lang/Enum {
 	public static final field AVERAGE Lcom/datadog/android/rum/configuration/VitalsUpdateFrequency;
 	public static final field FREQUENT Lcom/datadog/android/rum/configuration/VitalsUpdateFrequency;

Diff for: features/dd-sdk-android-rum/src/main/kotlin/com/datadog/android/rum/RumConfiguration.kt

@@ -9,6 +9,7 @@ package com.datadog.android.rum
 import android.os.Looper
 import androidx.annotation.FloatRange
 import com.datadog.android.event.EventMapper
+import com.datadog.android.rum.configuration.SlowFrameListenerConfiguration
 import com.datadog.android.rum.configuration.VitalsUpdateFrequency
 import com.datadog.android.rum.event.ViewEventMapper
 import com.datadog.android.rum.internal.RumFeature
@@ -283,6 +284,34 @@ data class RumConfiguration internal constructor(
             return this
         }
 
+        /**
+         * The SlowFramesListener provides statistical data to help identify performance issues related to UI rendering:
+         *
+         * - slowFrames: A list of records containing the timestamp and duration of frames where users experience
+         *   jank frames within the given view.
+         *
+         * - slowFrameRate: The rate of slow frames encountered during the view's lifetime.
+         *
+         * - freezeRate: The rate of freeze occurrences during the view's lifetime.
+         *
+         *
+         *
+         * This configuration sets the parameters for the SlowFramesListener, which are used to calculate the slow frames array,
+         * slow frame ratio, and freeze ratio. For additional details, refer to [SlowFrameListenerConfiguration].
+         *
+         * Assigning a null value to this property will disable the SlowFramesListener and stop the computation of the
+         * associated rates.
+         *
+         * @param slowFrameListenerConfiguration The configuration to be applied to the SlowFramesListener.
+         */
+        @ExperimentalRumApi
+        fun setSlowFrameListenerConfiguration(
+            slowFrameListenerConfiguration: SlowFrameListenerConfiguration?
+        ): Builder {
+            rumConfig = rumConfig.copy(slowFrameListenerConfiguration = slowFrameListenerConfiguration)
+            return this
+        }
+
         /**
          * Builds a [RumConfiguration] based on the current state of this Builder.
          */

Diff for: features/dd-sdk-android-rum/src/main/kotlin/com/datadog/android/rum/configuration/SlowFrameListenerConfiguration.kt

@@ -0,0 +1,63 @@
+/*
+ * Unless explicitly stated otherwise all files in this repository are licensed under the Apache License Version 2.0.
+ * This product includes software developed at Datadog (https://www.datadoghq.com/).
+ * Copyright 2016-Present Datadog, Inc.
+ */
+package com.datadog.android.rum.configuration
+
+/**
+ * The SlowFramesListener provides various statistics to assist in identifying UI performance issues:
+ *
+ * - slowFrames: A list of records containing the timestamp and duration of frames where users experience
+ *   jank frames within the given view.
+ *
+ * - slowFrameRate: The rate of slow frames encountered during the view's lifetime.
+ *
+ * - freezeRate: The rate of freeze occurrences during the view's lifetime.
+ *
+ * This class defines thresholds for frame duration to classify frames based on their duration type.
+ *
+ * @param maxSlowFramesAmount The maximum number of slow frame records to track for each view.
+ * The default value is 1000.
+ *
+ * @param maxSlowFrameThresholdNs The threshold (in nanoseconds) used to classify a frame as slow.
+ * Frames with durations exceeding this threshold will not be considered slow and will not affect the
+ * [com.datadog.android.rum.model.ViewEvent.ViewEventView.slowFramesRate].
+ * The default value is 700,000,000 ns (700 ms).
+ *
+ * @param continuousSlowFrameThresholdNs The threshold (in nanoseconds) used to classify a frame as continuously slow.
+ * If two consecutive slow frames are recorded and the delay between them is less than this threshold, the previous frame
+ * record will be updated rather than adding a new one.
+ * The default value is 16,666,666 ns (approximately 1/60 fps).
+ *
+ * @param freezeDurationThreshold The duration (in nanoseconds) used to classify a frame as a freeze frame.
+ * The cumulative duration of such freezes contributes to the calculation of the
+ * [com.datadog.android.rum.model.ViewEvent.ViewEventView.freezeRate].
+ * The default value is 5,000,000,000 ns (5 seconds).
+ *
+ * @param minViewLifetimeThresholdNs The minimum lifetime (in nanoseconds) a view must have before it is considered
+ * for monitoring. The default value is 100,000,000 ns (100 ms).
+ */
+
+data class SlowFrameListenerConfiguration(
+    internal val maxSlowFramesAmount: Int = DEFAULT_SLOW_FRAME_RECORDS_MAX_AMOUNT,
+    internal val maxSlowFrameThresholdNs: Long = DEFAULT_FROZEN_FRAME_THRESHOLD_NS,
+    internal val continuousSlowFrameThresholdNs: Long = DEFAULT_CONTINUOUS_SLOW_FRAME_THRESHOLD_NS,
+    internal val freezeDurationThreshold: Long = DEFAULT_FREEZE_DURATION_NS,
+    internal val minViewLifetimeThresholdNs: Long = DEFAULT_VIEW_LIFETIME_THRESHOLD_NS
+) {
+
+    companion object {
+        /**
+         * A default configuration of the SlowFrameListenerConfiguration class with all parameters set to their default values.
+         */
+        val DEFAULT: SlowFrameListenerConfiguration = SlowFrameListenerConfiguration()
+
+        // Taking into account each Hitch takes 64B in the payload, we can have 64KB max per view event
+        private const val DEFAULT_SLOW_FRAME_RECORDS_MAX_AMOUNT: Int = 1000
+        private const val DEFAULT_CONTINUOUS_SLOW_FRAME_THRESHOLD_NS: Long = 16_666_666L // 1/60 fps in nanoseconds
+        private const val DEFAULT_FROZEN_FRAME_THRESHOLD_NS: Long = 700_000_000 // 700ms
+        private const val DEFAULT_FREEZE_DURATION_NS: Long = 5_000_000_000L // 5s
+        private const val DEFAULT_VIEW_LIFETIME_THRESHOLD_NS: Long = 100_000_000L // 100ms
+    }
+}

Diff for: features/dd-sdk-android-rum/src/main/kotlin/com/datadog/android/rum/internal/RumFeature.kt

@@ -38,6 +38,7 @@ import com.datadog.android.internal.telemetry.InternalTelemetryEvent
 import com.datadog.android.rum.GlobalRumMonitor
 import com.datadog.android.rum.RumErrorSource
 import com.datadog.android.rum.RumSessionListener
+import com.datadog.android.rum.configuration.SlowFrameListenerConfiguration
 import com.datadog.android.rum.configuration.VitalsUpdateFrequency
 import com.datadog.android.rum.internal.anr.ANRDetectorRunnable
 import com.datadog.android.rum.internal.debug.UiRumDebugListener
@@ -152,7 +153,7 @@ internal class RumFeature(
         this.appContext = appContext
         initialResourceIdentifier = configuration.initialResourceIdentifier
         lastInteractionIdentifier = configuration.lastInteractionIdentifier
-        slowFramesListener = DefaultSlowFramesListener()
+
         dataWriter = createDataWriter(
             configuration,
             sdkCore as InternalSdkCore
@@ -191,6 +192,8 @@ internal class RumFeature(
             initializeANRDetector()
         }
 
+        initializeSlowFrameListener()
+
         registerTrackingStrategies(appContext)
 
         sessionListener = configuration.sessionListener
@@ -200,6 +203,25 @@ internal class RumFeature(
         initialized.set(true)
     }
 
+    private fun initializeSlowFrameListener() {
+        val slowFrameListenerConfiguration = configuration.slowFrameListenerConfiguration
+        slowFramesListener = if (slowFrameListenerConfiguration != null) {
+            sdkCore.internalLogger.log(
+                InternalLogger.Level.INFO,
+                InternalLogger.Target.USER,
+                { SLOW_FRAME_MONITORING_ENABLED_MESSAGE }
+            )
+            DefaultSlowFramesListener(slowFrameListenerConfiguration)
+        } else {
+            sdkCore.internalLogger.log(
+                InternalLogger.Level.INFO,
+                InternalLogger.Target.USER,
+                { SLOW_FRAME_MONITORING_DISABLED_MESSAGE }
+            )
+            NoOpSlowFramesListener()
+        }
+    }
+
     override val requestFactory: RequestFactory by lazy {
         RumRequestFactory(
             customEndpointUrl = configuration.customEndpointUrl,
@@ -571,6 +593,7 @@ internal class RumFeature(
         val sessionListener: RumSessionListener,
         val initialResourceIdentifier: InitialResourceIdentifier,
         val lastInteractionIdentifier: LastInteractionIdentifier?,
+        val slowFrameListenerConfiguration: SlowFrameListenerConfiguration?,
         val additionalConfig: Map<String, Any>,
         val trackAnonymousUser: Boolean
     )
@@ -618,7 +641,8 @@ internal class RumFeature(
             initialResourceIdentifier = TimeBasedInitialResourceIdentifier(),
             lastInteractionIdentifier = TimeBasedInteractionIdentifier(),
             additionalConfig = emptyMap(),
-            trackAnonymousUser = true
+            trackAnonymousUser = true,
+            slowFrameListenerConfiguration = null
         )
 
         internal const val EVENT_MESSAGE_PROPERTY = "message"
@@ -642,6 +666,10 @@ internal class RumFeature(
                 " where mandatory message field is either missing or has a wrong type."
         internal const val DEVELOPER_MODE_SAMPLE_RATE_CHANGED_MESSAGE =
             "Developer mode enabled, setting RUM sample rate to 100%."
+        internal const val SLOW_FRAME_MONITORING_ENABLED_MESSAGE =
+            "Slow frames monitoring enabled."
+        internal const val SLOW_FRAME_MONITORING_DISABLED_MESSAGE =
+            "Slow frames monitoring disabled."
         internal const val RUM_FEATURE_NOT_YET_INITIALIZED =
             "RUM feature is not initialized yet, you need to register it with a" +
                 " SDK instance by calling SdkCore#registerFeature method."

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

@@ -915,7 +915,7 @@ internal open class RumViewScope(
         }
 
         val uiSlownessReport = slowFramesListener.resolveReport(viewId)
-        val freezeRate = uiSlownessReport.anrDurationRate(stoppedNanos)
+        val freezeRate = uiSlownessReport.freezeFramesRate(stoppedNanos)
         val slowFramesRate = uiSlownessReport.slowFramesRate(stoppedNanos)
         val slowFrames = uiSlownessReport.slowFramesRecords.map {
             ViewEvent.SlowFrame(

Diff for: features/dd-sdk-android-rum/src/main/kotlin/com/datadog/android/rum/internal/domain/state/ViewUIPerformanceReport.kt

@@ -41,7 +41,7 @@ internal data class ViewUIPerformanceReport(
         else -> 0.0
     }
 
-    fun anrDurationRate(viewEndedTimeStamp: Long): Double = when {
+    fun freezeFramesRate(viewEndedTimeStamp: Long): Double = when {
         viewEndedTimeStamp - viewStartedTimeStamp <= minViewLifetimeThresholdNs -> 0.0
         else -> max(
             0.0,

Diff for: features/dd-sdk-android-rum/src/main/kotlin/com/datadog/android/rum/internal/metric/slowframes/SlowFramesListener.kt

@@ -8,6 +8,7 @@ package com.datadog.android.rum.internal.metric.slowframes
 import androidx.annotation.MainThread
 import androidx.annotation.WorkerThread
 import androidx.metrics.performance.FrameData
+import com.datadog.android.rum.configuration.SlowFrameListenerConfiguration
 import com.datadog.android.rum.internal.domain.FrameMetricsData
 import com.datadog.android.rum.internal.domain.state.SlowFrameRecord
 import com.datadog.android.rum.internal.domain.state.ViewUIPerformanceReport
@@ -24,11 +25,7 @@ internal interface SlowFramesListener : FrameStateListener {
 }
 
 internal class DefaultSlowFramesListener(
-    internal val maxSlowFramesAmount: Int = DEFAULT_SLOW_FRAME_RECORDS_MAX_AMOUNT,
-    internal val frozenFrameThresholdNs: Long = DEFAULT_FROZEN_FRAME_THRESHOLD_NS,
-    internal val continuousSlowFrameThresholdNs: Long = DEFAULT_CONTINUOUS_SLOW_FRAME_THRESHOLD_NS,
-    internal val anrDuration: Long = DEFAULT_ANR_DURATION_NS,
-    internal val minViewLifetimeThresholdNs: Long = DEFAULT_VIEW_LIFETIME_THRESHOLD_NS
+    internal val configuration: SlowFrameListenerConfiguration
 ) : SlowFramesListener {
 
     @Volatile
@@ -50,8 +47,8 @@ internal class DefaultSlowFramesListener(
         @Suppress("UnsafeThirdPartyFunctionCall") // can't have NPE here
         val report = slowFramesRecords.remove(viewId) ?: ViewUIPerformanceReport(
             System.nanoTime(),
-            maxSlowFramesAmount,
-            minViewLifetimeThresholdNs
+            configuration.maxSlowFramesAmount,
+            configuration.minViewLifetimeThresholdNs
         )
 
         // making sure that report is not partially updated
@@ -73,7 +70,7 @@ internal class DefaultSlowFramesListener(
             // Updating frames statistics
             report.totalFramesDurationNs += frameDurationNs
 
-            if (frameDurationNs > frozenFrameThresholdNs || !volatileFrameData.isJank) {
+            if (frameDurationNs > configuration.maxSlowFrameThresholdNs || !volatileFrameData.isJank) {
                 // Frame duration is too big to be considered as a slow frame or not jank
                 return
             }
@@ -83,7 +80,9 @@ internal class DefaultSlowFramesListener(
             val delaySinceLastUpdate = frameStartedTimestampNs -
                 (previousSlowFrameRecord?.startTimestampNs ?: frameStartedTimestampNs)
 
-            if (previousSlowFrameRecord == null || delaySinceLastUpdate > continuousSlowFrameThresholdNs) {
+            if (previousSlowFrameRecord == null ||
+                delaySinceLastUpdate > configuration.continuousSlowFrameThresholdNs
+            ) {
                 // No previous slow frame record or amount of time since the last update
                 // is significant enough to consider it idle - adding a new slow frame record.
                 if (frameDurationNs > 0) {
@@ -96,7 +95,7 @@ internal class DefaultSlowFramesListener(
                 // It's a continuous slow frame – increasing duration
                 previousSlowFrameRecord.durationNs = min(
                     previousSlowFrameRecord.durationNs + frameDurationNs,
-                    frozenFrameThresholdNs - 1
+                    configuration.maxSlowFrameThresholdNs - 1
                 )
             }
         }
@@ -105,7 +104,7 @@ internal class DefaultSlowFramesListener(
     @WorkerThread
     override fun onAddLongTask(durationNs: Long) {
         val view = currentViewId
-        if (durationNs >= anrDuration && view != null) {
+        if (durationNs >= configuration.freezeDurationThreshold && view != null) {
             val report = getViewPerformanceReport(view)
             synchronized(report) { report.anrDurationNs += durationNs }
         }
@@ -119,17 +118,8 @@ internal class DefaultSlowFramesListener(
     private fun getViewPerformanceReport(viewId: String) = slowFramesRecords.getOrPut(viewId) {
         ViewUIPerformanceReport(
             currentViewStartedTimeStampNs,
-            maxSlowFramesAmount,
-            minimumViewLifetimeThresholdNs = minViewLifetimeThresholdNs
+            configuration.maxSlowFramesAmount,
+            minimumViewLifetimeThresholdNs = configuration.minViewLifetimeThresholdNs
         )
     }
-
-    companion object {
-        // Taking into account each Hitch takes 64B in the payload, we can have 64KB max per view event
-        private const val DEFAULT_SLOW_FRAME_RECORDS_MAX_AMOUNT: Int = 1000
-        private const val DEFAULT_CONTINUOUS_SLOW_FRAME_THRESHOLD_NS: Long = 16_666_666L // 1/60 fps in nanoseconds
-        private const val DEFAULT_FROZEN_FRAME_THRESHOLD_NS: Long = 700_000_000 // 700ms
-        private const val DEFAULT_ANR_DURATION_NS: Long = 5_000_000_000L // 5s
-        private const val DEFAULT_VIEW_LIFETIME_THRESHOLD_NS: Long = 100_000_000L // 100ms
-    }
 }