Monitoring capabilities of Dynatrace Android Gradle plugin

With the following configuration options, you can customize OneAgent monitoring capabilities and fine-tune the auto-instrumentation process for these features.

User action monitoring

OneAgent creates user actions based on the UI components that trigger these actions and automatically combines user action data with other monitoring data, such as information on web requests and crashes. OneAgent extends the lifetime of user actions to properly aggregate them with other events that are executed in a background thread or immediately after a user action.

Configure user action monitoring

You can configure user action monitoring using the timeout and maxDuration properties. All user action monitoring related properties are part of UserAction DSL, so configure them via the userAction block.

gradlecopydownload
dynatrace {
    configurations {
        sampleConfig {
            userActions {
                // your user action monitoring configuration
            }
        }
    }
}

gradlecopydownload
configure<com.dynatrace.tools.android.dsl.DynatraceExtension> {
    configurations {
        create("sampleConfig") {
            userActions {
                // your user action monitoring configuration
            }
        }
    }
}

With the timeout property, you can configure the time during which OneAgent can add other events to the newly created user action. When another user interaction is detected, OneAgent stops adding events to the user action of the previous interaction, regardless of the configured timeout value. Instead, OneAgent adds events only to the user action from the current user interaction.

When the timeout time period expires, OneAgent checks if there are open events and waits until these events are completed. With the maxDuration property, you can configure the maximum duration of these user actions. If an open event, for example, a web request, is still not finished after this period, OneAgent removes these events from the user action and closes the user action with an appropriate end time value.

Specify the value for both properties in milliseconds. The value of the maxDuration property must be equal to or greater than the value of the timeout property.

OneAgent also reports user actions that don't contain child events. To discard such user actions, use the emptyActions property.

Disable user action monitoring

You can completely deactivate user action monitoring with the enabled property. In this case, all other properties are ignored, so only specify the enabled property to avoid confusion.

gradlecopydownload
dynatrace {
    configurations {
        sampleConfig {
            userActions.enabled false
        }
    }
}

gradlecopydownload
configure<com.dynatrace.tools.android.dsl.DynatraceExtension> {
    configurations {
        create("sampleConfig") {
            userActions.enabled(false)
        }
    }
}

User action monitoring sensors

The plugin automatically instruments the following listeners and methods:

• Android
  • android.view.View$OnClickListener
  • android.widget.AdapterView$OnItemClickListener
  • android.widget.AdapterView$OnItemSelectedListener
  • android.app.Activity.onOptionsItemSelected
  • android.view.MenuItem$OnMenuItemClickListener
• AndroidX
  • androidx.viewpager.widget.ViewPager$OnPageChangeListener
  • androidx.swiperefreshlayout.widget.SwipeRefreshLayout$OnRefreshListener
• Android Support
  • android.support.v4.view.ViewPager$OnPageChangeListener
  • android.support.v4.widget.SwipeRefreshLayout$OnRefreshListener

You can deactivate specific sensors via the UserAction Sensor DSL properties and configure it inside the sensors block.

gradlecopydownload
dynatrace {
    configurations {
        sampleConfig {
            userActions {
                sensors {
                    // fine-tune the sensors if necessary
                }
            }
        }
    }
}

gradlecopydownload
configure<com.dynatrace.tools.android.dsl.DynatraceExtension> {
    configurations {
        create("sampleConfig") {
            userActions {
                sensors {
                    // fine-tune the sensors if necessary
                }
            }
        }
    }
}

User action naming

To construct user action names, OneAgent captures the control title from different attributes depending on the listener or method used. See the table below for details.

Mask user actions

Dynatrace Android Gradle plugin version 8.249+

By default, user action names are derived from UI element titles, for example, button or menu item titles. In rare circumstances, email addresses, usernames, or other personal information might be unintentionally included in user action names. This happens when this information is included in parameters used for control titles, resulting in user action names such as Touch on Account 123456.

If such personal information appears in your application's user action names, enable user action masking. OneAgent will replace all Touch on <control title> action names with the class name of the control that the user touched, for example:

• Touch on Account 123456 > Touch on Button
• Touch on Transfer all amount > Touch on Switch
• Touch on Account settings > Touch on ActionMenuItem

You can enable user action masking with the namePrivacy property of the UserAction DSL.

gradlecopydownload
dynatrace {
    configurations {
        sampleConfig {
            userActions {
                namePrivacy true
            }
        }
    }
}

kotlincopydownload
configure<com.dynatrace.tools.android.dsl.DynatraceExtension> {
    configurations {
        create("sampleConfig") {
            userActions {
                namePrivacy(true)
            }
        }
    }
}

Modify user actions

OneAgent for Android creates user actions based on interactions of your application's users. These actions are different from custom actions and are sometimes called autogenerated actions. We also refer to them as user actions.

You can modify or even cancel user actions.

Modify a specific user action

With Dynatrace.modifyUserAction, you can modify the current user action. You can change the user action name and report events, values, and errors. You can also cancel a user action.

The Dynatrace.modifyUserAction method accepts an implementation of UserActionModifier as a parameter, which provides you with the current mutable ModifiableUserAction object.

Allowed operations on this user action object are as follows:

• getActionName
• setActionName
• reportEvent
• reportValue
• reportError
• OneAgent for Android version 8.241+ cancel

You can modify a user action only while it is still open. If the user action times out before it is modified, the modification has no effect. We recommend that you invoke Dynatrace.modifyUserAction inside the instrumented listener method and don't call this method from a different thread.

In the following example, we're using a calculator app to show you how to change the name of the user action that is created for the button click and how to report a value to the action.

javacopydownload
button.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View v) {
        int result = calc();
        // we use Java 8 language features here. You can also use anonymous classes instead of lambdas
        Dynatrace.modifyUserAction(userAction -> {
            userAction.setActionName("Click on Calculate");
            userAction.reportValue("Calculated result", result);
        });
        showResult(result);
    }
});

kotlincopydownload
button.setOnClickListener {
    val result = calc()
    Dynatrace.modifyUserAction { userAction ->
        userAction.actionName = "Click on Calculate"
        userAction.reportValue("Calculated result", result)
    }
    showResult(result)
}

Modify any user action

OneAgent for Android version 8.241+

You can modify user actions via Dynatrace.modifyUserAction. However, you can do that only for a specific user action, and you usually should know whether this user action is still open or not.

To overcome these limitations, we introduced a feature that allows you to receive a callback for every newly created user action. With this approach, you are notified about every new autogenerated user action, so you get a chance to update the user action name as well as report events, values, and errors. You can also cancel a user action.

You can register a callback that is invoked for each user action. UserActionModifier is set once at OneAgent startup via the DynatraceConfigurationBuilder#withAutoUserActionModifier method. After that, it is invoked each time OneAgent creates a user action. It is not invoked for custom actions.

Allowed operations are as follows:

• getActionName
• setName
• reportEvent
• reportValue
• reportError
• cancel

javacopydownload
Dynatrace.startup(this, new DynatraceConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconUrl>")
    .withAutoUserActionModifier(modifiableAction -> {
        if (modifiableAction.getActionName().contains("account ID")) {
            // remove personal information from the user action name
            modifiableAction.setActionName("Touch on Account");
        }
    })
    .buildConfiguration());

kotlincopydownload
Dynatrace.startup(this, DynatraceConfigurationBuilder("<YourApplicationID>", "<ProvidedBeaconUrl>")
    .withAutoUserActionModifier { modifiableAction: ModifiableUserAction ->
        if (modifiableAction.actionName.contains("account ID")) {
            // remove personal information from the user action name
            modifiableAction.actionName = "Touch on Account"
        }
    }
    .buildConfiguration())

Android data binding library

The Dynatrace Android Gradle plugin can instrument event logic and listeners that are defined via the data binding feature. If your app contains code similar to the official listener binding example, the plugin can detect the correct bytecode and instrument it.

xmlcopydownload
<?xml version="1.0" encoding="utf-8"?>
<layout xmlns:android="http://schemas.android.com/apk/res/android">
    <data>
        <variable name="task" type="com.android.example.Task" />
        <variable name="presenter" type="com.android.example.Presenter" />
    </data>
    <LinearLayout android:layout_width="match_parent" android:layout_height="match_parent">
        <Button android:layout_width="wrap_content" android:layout_height="wrap_content"
        android:onClick="@{() -> presenter.onSaveClick(task)}" />
    </LinearLayout>
</layout>

Define an event handler via XML attribute

The following example from the Android documentation shows how you can define an event handler via XML attributes.

xmlcopydownload
<?xml version="1.0" encoding="utf-8"?>
<Button xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/button_send"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="@string/button_send"
    android:onClick="sendMessage" />

javacopydownload
/** Called when the user touches the button */
public void sendMessage(View view) {
    // Do something in response to button click
}

kotlincopydownload
/** Called when the user touches the button */
fun sendMessage(view: View) {
    // Do something in response to button click
}

The Dynatrace Android Gradle plugin cannot determine the relationship between the button in the layout XML file and the sendMessage method in the activity. However, when your app uses the Appcompat library and your activities are derived from androidx.appcompat.app.AppCompatActivity, the plugin auto-instruments the delegation logic of the Appcompat library. If you don't use the Appcompat library, you must manually instrument these event handler methods because the plugin is unable to determine the connection between the bytecode and the layout XML file.

Web request monitoring

The Dynatrace Android Gradle plugin can automatically instrument and tag your web requests. To track web requests, OneAgent adds the x-dynatrace HTTP header with a unique value to the web request. This is required to correlate the server-side monitoring data to the corresponding mobile web request.

Configure web request monitoring

All web request monitoring related properties are part of WebRequest DSL, so configure these properties via the webRequests block.

gradlecopydownload
dynatrace {
    configurations {
        sampleConfig {
            webRequests {
                // your web request monitoring configuration
            }
        }
    }
}

gradlecopydownload
configure<com.dynatrace.tools.android.dsl.DynatraceExtension> {
    configurations {
        create("sampleConfig") {
            webRequests {
                // your web request monitoring configuration
            }
        }
    }
}

If a web request is triggered shortly after a monitored user interaction, OneAgent adds the web request as a child event to the monitored user action. OneAgent automatically truncates the query from the captured URL and only reports the domain name and path of your web requests.

Disable web request monitoring

You can completely deactivate web request monitoring with the enabled property. In this case, all other properties are ignored, so only specify the enabled property to avoid confusion.

gradlecopydownload
dynatrace {
    configurations {
        sampleConfig {
            webRequests.enabled false
        }
    }
}

gradlecopydownload
configure<com.dynatrace.tools.android.dsl.DynatraceExtension> {
    configurations {
        create("sampleConfig") {
            webRequests.enabled(false)
        }
    }
}

Web request monitoring sensors

The following HTTP frameworks are supported:

• HttpURLConnection
• OkHttp: Only version 3 and 4
• Apache HTTP Client: Only the Android-internal HTTP Client version¹

You can deactivate specific sensors via the WebRequest Sensor DSL properties and configure it inside the sensors block.

gradlecopydownload
dynatrace {
    configurations {
        sampleConfig {
            webRequests {
                sensors {
                    // fine-tune the sensors if necessary
                }
            }
        }
    }
}

gradlecopydownload
configure<com.dynatrace.tools.android.dsl.DynatraceExtension> {
    configurations {
        create("sampleConfig") {
            webRequests {
                sensors {
                    // fine-tune the sensors if necessary
                }
            }
        }
    }
}

Lifecycle monitoring

With lifecycle monitoring, OneAgent collects the following data:

• Application start event: Measures the timespan from Application.onCreate() to Activity.onPostResume() of the first activity.

  The application start event is not captured if the application starts up in the background and does not promptly open an activity or if auto-start injection is disabled.

• Activity display: Measures the timespan from Activity.onCreate(Bundle) to Activity.onPostResume() and reports the time of each activity lifecycle state that is entered.
• Activity redisplay: Measures the time required to redisplay a previously created activity and reports the time of each activity lifecycle state that is entered until the activity is visible again.

Configure lifecycle monitoring

Lifecycle events are either part of existing user actions, or they create a new user action and attach the display or redisplay lifecycle action to it. All lifecycle monitoring related properties are part of Lifecycle DSL, so configure them via the lifecycle block.

gradlecopydownload
dynatrace {
    configurations {
        sampleConfig {
            lifecycle {
                // your lifecycle monitoring configuration
            }
        }
    }
}

gradlecopydownload
configure<com.dynatrace.tools.android.dsl.DynatraceExtension> {
    configurations {
        create("sampleConfig") {
            lifecycle {
                // your lifecycle monitoring configuration
            }
        }
    }
}

Disable lifecycle monitoring

You can deactivate lifecycle monitoring with the enabled property. In this case, all other properties are ignored, so specify only the enabled property.

gradlecopydownload
dynatrace {
    configurations {
        sampleConfig {
            lifecycle.enabled false
        }
    }
}

gradlecopydownload
configure<com.dynatrace.tools.android.dsl.DynatraceExtension> {
    configurations {
        create("sampleConfig") {
            lifecycle.enabled(false)
        }
    }
}

Lifecycle monitoring sensors

You can deactivate specific sensors via the Lifecycle Sensor DSL properties and configure it inside the sensors block.

gradlecopydownload
dynatrace {
    configurations {
        sampleConfig {
            lifecycle {
                sensors {
                    // fine-tune the sensors if necessary
                }
            }
        }
    }
}

gradlecopydownload
configure<com.dynatrace.tools.android.dsl.DynatraceExtension> {
    configurations {
        create("sampleConfig") {
            lifecycle {
                sensors {
                    // fine-tune the sensors if necessary
                }
            }
        }
    }
}

Crash reporting

OneAgent captures all unhandled exceptions and errors and sends the crash report immediately to the server. The Android crash report includes the occurrence time and the full stack trace of the exception.

If a crash is triggered shortly after a monitored user interaction, OneAgent adds the crash as a child event to the monitored user action.

You can deactivate crash reporting with the crashReporting property.

gradlecopydownload
dynatrace {
    configurations {
        sampleConfig {
            crashReporting false
        }
    }
}

gradlecopydownload
configure<com.dynatrace.tools.android.dsl.DynatraceExtension> {
    configurations {
        create("sampleConfig") {
            crashReporting(false)
        }
    }
}

Rage tap detection

Dynatrace Android Gradle plugin version 8.231+

When your mobile app doesn't respond quickly, a text label looks like a button, or a toggle is hidden under another toggle, users may repeatedly tap the screen or affected UI control in helpless frustration. OneAgent detects such behavior as a rage tap.

You can deactivate rage tap detection using the detectRageTaps property of the BehavioralEvents DSL.

gradlecopydownload
dynatrace {
    configurations {
        sampleConfig {
            behavioralEvents {
                detectRageTaps false
            }
        }
    }
}

kotlincopydownload
configure<com.dynatrace.tools.android.dsl.DynatraceExtension> {
    configurations {
        create("sampleConfig") {
            behavioralEvents {
                detectRageTaps(false)
            }
        }
    }
}

Location monitoring

When enabled, OneAgent appends the captured end user positions to the monitoring data. To protect the privacy of the end user, OneAgent captures only three fractional digits of GPS coordinates.

You can activate the location monitoring feature with the locationMonitoring property.

gradlecopydownload
dynatrace {
    configurations {
        sampleConfig {
            locationMonitoring true
        }
    }
}

gradlecopydownload
configure<com.dynatrace.tools.android.dsl.DynatraceExtension> {
    configurations {
        create("sampleConfig") {
            locationMonitoring(true)
        }
    }
}

OneAgent only captures location data that is already processed in your application. OneAgent doesn't request additional location data from the Android SDK. If your app doesn't process location data, this feature isn't enabled. When location monitoring is disabled or no location information is available, Dynatrace uses IP addresses to determine the location of the user.

The plugin supports the following location listener:

• android.location.LocationListener