RUM-12062: Refactor the configuration and integration of the RUM Debug Widget #2975

kikoveiga · 2025-10-31T15:01:00Z

What does this PR do?

Simplifies the configuration of the RUM Debug Widget. Customers can now simply use enableRumDebugWidget() in their RumConfiguration.Builder.
Adds documentation for this configuration in the README.md.
Replaced manual overlay lifecycle management with automatic OverlayManager using activity lifecycle callbacks.

Motivation

Configuration was too complex for customers, where some unnecessary APIs had to be exposed. The DefaultInsightsOverlay had to be manually attached to every activity by customers.

Review checklist (to be filled by reviewers)

Feature or bugfix MUST have appropriate tests (unit, integration, e2e)
Make sure you discussed the feature or bugfix with the maintaining team in an Issue
Make sure each commit and the PR mention the Issue number (cf the CONTRIBUTING doc)

…Initializer and AutoStarter

…n LICENSE 3rd party

…/change-widget-activity-configuration

datadog-official · 2025-11-03T14:54:25Z

🎯 Code Coverage
• Patch Coverage: 100.00%
• Total Coverage: 70.05% (-0.26%)

View detailed report

_{This comment will be updated automatically if new data arrives.

🔗 Commit SHA: 7c2f184 | Docs | Datadog PR Page | Was this helpful? Give us feedback!}

…a/RUM-12062/change-widget-activity-configuration

Copilot

Pull Request Overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

...dget/src/main/kotlin/com/datadog/android/insights/internal/overlay/DefaultInsightsOverlay.kt

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

...debug-widget/src/main/kotlin/com/datadog/android/insights/internal/overlay/OverlayManager.kt

...dget/src/main/kotlin/com/datadog/android/insights/internal/overlay/DefaultInsightsOverlay.kt

aleksandr-gringauz · 2025-11-05T14:11:03Z

...dget/src/main/kotlin/com/datadog/android/insights/internal/overlay/DefaultInsightsOverlay.kt

+        }
+
+        root?.let { v ->
+            if (v.parent != parent) {


Why is this if needed? If I understand correctly it is always false, because we only set root using the code above:

val overlayView = activity.layoutInflater.inflate( R.layout.layout_dd_insights_overlay, parent, false ) root = overlayView

This is false for the first call to attach(), but for the next calls it could be true when moving the overlay between activities, so we should check to prevent reattaching, for example.

...dget/src/main/kotlin/com/datadog/android/insights/internal/overlay/DefaultInsightsOverlay.kt

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

aleksandr-gringauz · 2025-11-05T14:33:26Z

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

+
+    @Suppress("UnsafeThirdPartyFunctionCall")
+    runCatching {
+        val clazz = Class.forName("com.datadog.android.insights.internal.RumDebugWidget")


What do you think of the following option to avoid reflection?

setInsightsCollector is in _RumInternalProxy. https://github.com/DataDog/dd-sdk-android/pull/2975/files#r2494746331.

Then in this enableRumDebugWidget you call:

val insightsCollector = DefaultInsightsCollector() _RumInternalProxy.setInsightsCollector(builder, insightsCollector) OverlayManager(insightsCollector).start(application)

upd

Sorry, forgot an important part. This file should be moved to dd-sdk-android-rum-debug-widget

All this reflection inside the RUM module is because the rum-debug-widget module is supposed to only be included in debug builds, by using debugImplementation in the build.gradle file. Otherwise yes, we would put this extension to RumConfiguration.Builder in the rum-debug-widget module, but we want to safeguard the customer from crashing the app in production.

All this reflection inside the RUM module is because the rum-debug-widget module is supposed to only be included in debug builds, by using debugImplementation in the build.gradle file.

If the customers want to use debugImplementation("dd-sdk-android-rum-debug-widget"), they can create a sourceSet for debug and call enableRumDebugWidget from there.

But in that case you will have to keep another copy of Application class there. Don you think it might be too complex in general for the customers so they gonna skip that option and add widget as a dependency directly in the app ending with it in a production build ?

As discussed with @satween, we can keep the reflection and don't need the consumer/proguard rules to clean this code. The refactoring on the enableRumDebugWidget function handles this well (as also explained in this comment).

and don't need the consumer/proguard rules to clean this code

consumer-rules.pro are needed not for cleaning, but so that the code of dd-sdk-android-rum-debug-widget isn't removed from the application by R8. See this example
16215ba. You can run sample:kotlin in debug (I enabled R8 there to demonstrate) and see that RumDebugWidget.enable isn't called.

RumDebugWidget was removed from the APK of the sample app by R8.

You are right, added the consumer-rules.pro file.

the rum-debug-widget module is supposed to only be included in debug builds

but at the same time we have allowInRelease argument in this method.

Overall, it is a debug tool which may be used in the release build to verify SDK integration (it makes sense if we merge the functionality of RumMonitor.debug here, because customers may want to check RUM view names in release builds if they are based on the class names).

I think we simply may want to take integration approach used by LeakCanary, I guess there it is closer to what @aleksandr-gringauz is proposing?

I think we simply may want to take integration approach used by LeakCanary, I guess there it is closer to what @aleksandr-gringauz is proposing?

I suppose yes, it is similar:

In the docs it suggests you use debugImplementation.

Here there is an example of doing custom configuration in debug sourceSet.

One thing to mention is that custom configuration is optional, LeakCanary will start doing something just when you add the dependency. It does that with the help of multiple ContentProviders link. I'm not suggesting doing the same thing in our case (we don't need it), just exploring what they are doing.

...debug-widget/src/main/kotlin/com/datadog/android/insights/internal/overlay/OverlayManager.kt

...bug-widget/src/main/kotlin/com/datadog/android/insights/internal/DefaultInsightsCollector.kt

aleksandr-gringauz · 2025-11-05T14:50:07Z

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

+ */
+fun RumConfiguration.Builder.enableRumDebugWidget(
+    application: Application,
+    enabled: Boolean = application.isDebuggable()


IMHO this enabled parameter is useless. The method is called enableRumDebugWidget. If the customer calls it, they want to enable it.

The idea here, and as dicussed with @satween, is that we wanted to safeguard the customer from accidentally enabling this in release builds. For this, they would have to explicitly pass true in the enabled parameter.

Well the idea was to use Build.DEBUG constant, not the application.isDebuggable().

Let's try to remove the enabled parameter and put whole logic into the if(BuildConfig.DEBUG) scope as suggested by @aleksandr-gringauz in the comment above

if(BuildConfig.DEBUG)

I don't understand how this will work. Each gradle module has its own BuildConfig class and it is a statically generated thing. BuildConfig.DEBUG will be equal to false in the published artifacts of all modules.

What I was talking about is if(BuildConfig.DEBUG) where BuildConfig is from the app module of the customer.

I don't understand how this will work. Each gradle module has its own BuildConfig class and it is a statically
generated thing. BuildConfig.DEBUG will be equal to false in the published artifacts of all modules.

I thought there is some R8 feature that I missed.

Let me explain the problem we are trying to solve here: We want to let customer use dd-android-sdk-rum-widget module for debug the Datadog SDK integration. We are expecting that the widget is going to be used only for the debug purposes, but in the other hand - want to make it handy and easy to use.

From that perspective we want to avoid:

Accidentally adding widget into release build of the customer's app (at the first glance it could be solved with the debugImplementation)

Add the additional effort to manually remove usages of the widget from the release build. In case if customer will add widget as a debugImplementation dependency, then use it in the code - it will break the compilation of the release build.

So I see several options to do so:

Create additional debug source on the customer's side - but this could be hard for some projects. Debug version of the Application has to be maintained and seems overkill for just a widget.

Use reflection to check if widget is added as a dependency in the runtime.

To reduce the impact of the reflection to the application launch time we could ask customer to provide BuildConfig.DEBUG value with the enabled parameter to not call reflection in the production.

WDYT ?

To reduce the impact of the reflection to the application launch time we could ask customer to provide BuildConfig.DEBUG value with the enabled parameter to not call reflection in the production.

IIUC you are proposing the following API:

fun RumConfiguration.Builder.enableRumDebugWidget( application: Application, enabled: Boolean )

And in the documentation we tell the customers that they can pass BuildConfig.DEBUG as enabled parameter.

Ok, this will work.

To me 2 "enable" words in one signature look confusing, I would probably call it setRumDebugWidgetEnabled(enabled) or if we want to call enableRumDebugWidget - just drop the enabled argument.

This is why I initially started this particular thread about enabled argument.

Not blocking the PR.

I changed the argument enabled to allowInRelease which defaults to false. This safeguards customers from accidentally enabling this in production, where the reflection would run with no success, as the dd-sdk-android-rum-debug-widget module should be added as debugImplementation in the build.gradle file. To really use the widget in release builds (e.g. local testing), customers should set allowInRelease to true and add the module as implementation. This is well explained in the function documentation.

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

...debug-widget/src/main/kotlin/com/datadog/android/insights/internal/overlay/OverlayManager.kt

aleksandr-gringauz · 2025-11-06T10:22:04Z

...dget/src/main/kotlin/com/datadog/android/insights/internal/overlay/DefaultInsightsOverlay.kt

+    private var isTransitioning: Boolean = false
+
+    @Suppress("LongMethod")
+    internal fun attach(activity: Activity) {


Not blocking for this PR, just some thoughts.

The current API for the widget integration allows either to enable it so that is visible everywhere in the app or not enable it at all. Also it is impossible to programmatically hide it.

Big apps might have some kind of Debug view that contains things related to debugging. For example it might contain toggles for feature flags, some debugging tools specific for the app. In this case it would be convenient to be able to enable and disable our widget by clicking on some button there. But currently it is impossible.

Also apps might want to attach the view of the widget not to the root view of activity, but somewhere else (maybe some debug panel that can be swiped to the side?).

The idea behind this widget is that the customers could enable it while they work on SDK integration and then remove it completley. This is why I was thinking about adding it only as a debugImplentation dependency in order to prevent widget being available in release build of the app. Having an option to add this widget somewhere beside the root of activity a good idea in general, but would require much more effort to support (like the case with an app using only compose ui) and goes beside the scope of this initiative.
We just want to provide faster feedback loop for the developers that struggle to integrate the SDK.

The idea behind this widget is that the customers could enable it while they work on SDK integration and then remove it completley.

We just want to provide faster feedback loop for the developers that struggle to integrate the SDK.

So it isn't a widget for investigating application performance (it's memory usage, skipped frames, other things) but rather a widget for debugging sdk integration?

Yes, widget is for:

Validating the integration (e.g see if the SDK identifies the user actions correctly)

Debugging some issues like memory leaks or high CPU usage (but only in dev environment)

Not blocking the PR, just some ideas.

Debugging some issues like memory leaks or high CPU usage (but only in dev environment)

It could useful to be able to do it in some builds that are intended for QA-engineers or the builds that are used internally in the customer's company. These are usually release builds and are often implemented as a separate Gradle flavor.

Also performance issues are often investigated in release, because when you enable compiler optimizations the picture usually changes.

Having an option to add this widget somewhere beside the root of activity a good idea in general, but would require much more effort to support (like the case with an app using only compose ui) and goes beside the scope of this initiative.

The way it could be done is that we provide a custom android view (implemented in Android Views, not compose) as a public API. And inside it do something like GlobalRumMonitor.getInstance(sdkName).getInsightsCollector.subscribe { data -> updateWidget(data) } in this CustomView.onAttachedToWindow. sdkName should be provided by the customer's code either through a view's constructor or through a custom xml tag. Apps with Compose will be able to use it like this.

Yes, widget is for:

Validating the integration (e.g see if the SDK identifies the user actions correctly)

Then we have a to think what to do with RumMonitor.debug, because its purpose is also to debug SDK integration.

With this change we will have two "RUM debug" entrypoints.

Should we maybe unify things? WDYT?

… in release

0xnm · 2025-11-18T08:42:22Z

...oid-rum-debug-widget/src/main/kotlin/com/datadog/android/insights/internal/RumDebugWidget.kt

+@Suppress("OPT_IN_USAGE")
+internal object RumDebugWidget {
+
+    @JvmStatic


Is this needed, given that class is internal, so this method can be only called from Kotlin? Or is it to simplify reflection somehow?

0xnm · 2025-11-18T08:42:38Z

...oid-rum-debug-widget/src/main/kotlin/com/datadog/android/insights/internal/RumDebugWidget.kt

+import com.datadog.android.rum.RumConfiguration
+import com.datadog.android.rum._RumInternalProxy
+
+@Suppress("OPT_IN_USAGE")


is it needed?

0xnm · 2025-11-18T08:52:28Z

...es/dd-sdk-android-rum/src/test/kotlin/com/datadog/android/rum/RumConfigurationBuilderTest.kt


    @Test
-    fun `M use NoOpInsightsCollector W setInsightsCollector(null)`() {
+    fun `M use NoOpInsightsCollector W don't setInsightsCollector()`() {


Suggested change

fun `M use NoOpInsightsCollector W don't setInsightsCollector()`() {

fun `M use NoOpInsightsCollector W build() { default configuration }`() {

0xnm · 2025-11-18T08:57:34Z

...dget/src/main/kotlin/com/datadog/android/insights/internal/overlay/DefaultInsightsOverlay.kt

+    private var isTransitioning: Boolean = false
+
+    @Suppress("LongMethod")
+    internal fun attach(activity: Activity) {


Yes, widget is for:

Validating the integration (e.g see if the SDK identifies the user actions correctly)

Then we have a to think what to do with RumMonitor.debug, because its purpose is also to debug SDK integration.

With this change we will have two "RUM debug" entrypoints.

Should we maybe unify things? WDYT?

0xnm · 2025-11-18T09:04:08Z

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

+ * to prevent accidental exposure in production.
+ * @return The same [RumConfiguration.Builder] instance.
+ */
+fun RumConfiguration.Builder.enableRumDebugWidget(


why it is an extension method rather than class method?

0xnm · 2025-11-18T09:14:37Z

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

+
+    @Suppress("UnsafeThirdPartyFunctionCall")
+    runCatching {
+        val clazz = Class.forName("com.datadog.android.insights.internal.RumDebugWidget")


the rum-debug-widget module is supposed to only be included in debug builds

but at the same time we have allowInRelease argument in this method.

Overall, it is a debug tool which may be used in the release build to verify SDK integration (it makes sense if we merge the functionality of RumMonitor.debug here, because customers may want to check RUM view names in release builds if they are based on the class names).

I think we simply may want to take integration approach used by LeakCanary, I guess there it is closer to what @aleksandr-gringauz is proposing?

kikoveiga added 18 commits October 28, 2025 14:10

RUM-12062: Overlay now configurable directly in application

8a14888

RUM-12060: Remove repeated line

2cc148c

RUM-12060: Update README.md

69e0563

RUM-12060: Cut screenshot

b5d47a5

RUM-12060: Update screenshot

c48a483

RUM-12060: Update screenshot

53ec2ca

RUM-12060: Format README.md

47acfe5

RUM-12060: Push requested changes

d4296c2

RUM-12060: Update apiSurface

e49a7a9

RUM-12061: Continue unit and integration tests

a97e6d8

RUM-12061: Add more unit and integration tests

7ef18f0

RUM-12061: Finish tests

3590c10

RUM-12061: Fix formatting

07e024e

RUM-12062: Fixing rebase

ae7a408

RUM-12062: Begin reconfiguration of DefaultInsightsCollector with an …

8b92c71

…Initializer and AutoStarter

RUM-12062: Add RumConfiguration Builder extension function

48f38ac

RUM-12062: Improve overlay's animation and attaching to activities

c56bea9

RUM-12062: Add comments and fix magic numbers, dependencies missing i…

1e22471

…n LICENSE 3rd party

kikoveiga self-assigned this Oct 31, 2025

kikoveiga added 3 commits October 31, 2025 15:11

Merge branch 'kikoveiga/RUM-12061/add-tests' into kikoveiga/RUM-12062…

2971f00

…/change-widget-activity-configuration

Rollback one line

c53e593

RUM-12062: Add @ExperimentalRumApi annotation to OverlayManager.kt

d9504f7

Base automatically changed from kikoveiga/RUM-12061/add-tests to tvaleev/feature/innovation-week-07-04-25 November 3, 2025 09:44

kikoveiga requested a review from Copilot November 3, 2025 12:02

This comment was marked as resolved.

Sign in to view

kikoveiga added 2 commits November 3, 2025 12:25

RUM-12062: ChangeOverlayManager to class

e8efdbd

RUM-12062: Remove unused dependency

e1bdbed

kikoveiga added 2 commits November 3, 2025 15:19

Merge branch 'tvaleev/feature/innovation-week-07-04-25' into kikoveig…

69f3227

…a/RUM-12062/change-widget-activity-configuration

RUM-12062: Fix unit tests

c567d6a

kikoveiga added 4 commits November 4, 2025 11:11

RUM-12062: Begin reflection

29c1752

RUM-12062: Reflection working and README.md done

4c83907

RUM-12062: Remove unused lines in README.md

f3a66c9

RUM-12062: Clean up

4ead2c9

kikoveiga requested a review from Copilot November 4, 2025 18:40

Copilot AI reviewed Nov 4, 2025

View reviewed changes

kikoveiga added 4 commits November 5, 2025 09:57

RUM-12062: Test removal of unnecessary suppress

35dfe83

RUM-12062: Revert

0a8567b

RUM-12062: Revert

95e2389

RUM-12062: Improve documentation and clean up

cf9befe

kikoveiga marked this pull request as ready for review November 5, 2025 13:29

kikoveiga requested review from a team as code owners November 5, 2025 13:29

aleksandr-gringauz reviewed Nov 5, 2025

View reviewed changes

maycmlee approved these changes Nov 5, 2025

View reviewed changes

RUM-12062: Push suggested changes

e9e72d0

aleksandr-gringauz reviewed Nov 6, 2025

View reviewed changes

kikoveiga added 5 commits November 10, 2025 10:58

RUM-12062: Remove unnecessary annotations

e07a7eb

RUM-12062: Change enableRumDebugWidget function, now able to allow it…

2acb188

… in release

RUM-12062: Update API files

d7b2d05

RUM-12062: Move isDebuggable code inline

de79df8

RUM-12062: Update variable name

e131311

kikoveiga requested a review from aleksandr-gringauz November 12, 2025 15:21

RUM-12062: Add consumer-rules.pro file and other small improvements

703c3f4

kikoveiga requested a review from satween November 13, 2025 15:25

RUM-12062: Improve message of internal log

7c2f184

0xnm reviewed Nov 18, 2025

View reviewed changes

	fun `M use NoOpInsightsCollector W don't setInsightsCollector()`() {
	fun `M use NoOpInsightsCollector W build() { default configuration }`() {

RUM-12062: Refactor the configuration and integration of the RUM Debug Widget #2975

Are you sure you want to change the base?

RUM-12062: Refactor the configuration and integration of the RUM Debug Widget #2975

Uh oh!

Conversation

kikoveiga commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Motivation

Review checklist (to be filled by reviewers)

Uh oh!

This comment was marked as resolved.

Uh oh!

datadog-official bot commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aleksandr-gringauz Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aleksandr-gringauz Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kikoveiga Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aleksandr-gringauz Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aleksandr-gringauz Nov 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aleksandr-gringauz Nov 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kikoveiga commented Oct 31, 2025 •

edited

Loading

datadog-official bot commented Nov 3, 2025 •

edited

Loading

aleksandr-gringauz Nov 5, 2025 •

edited

Loading

aleksandr-gringauz Nov 5, 2025 •

edited

Loading

kikoveiga Nov 12, 2025 •

edited

Loading

aleksandr-gringauz Nov 18, 2025 •

edited

Loading

aleksandr-gringauz Nov 10, 2025 •

edited

Loading

aleksandr-gringauz Nov 10, 2025 •

edited

Loading

aleksandr-gringauz Nov 6, 2025 •

edited

Loading