Monitoring capabilities of DESK 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 internal user actions based on the UI components that trigger these actions and automatically combines them with other monitoring data, such as web requests and crashes. It extends the lifetime of these user actions to properly aggregate it with other events that are executed immediately after the user interaction or are executed in a background thread.

Configure user action monitoring

User action monitoring can be configured with the timeout and maxDuration properties. All user action monitoring related properties are part of UserAction DSL and must be configured via the userAction block:

Groovy Kotlin

desk {
    configurations {
        sampleConfig {
            userActions {
                // your user action monitoring configuration
            }
        }
    }
}

configure<com.desk.tools.android.dsl.DESKExtension> {
    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 will check 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 (like 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.

The value for both properties must be specified in milliseconds. The default value for the timeout property is 500 ms and the valid range is 100 ms - 5,000 ms. The default value of the maxDuration property is 60,000 ms (one minute) and the valid range is 100 ms - 540,000 ms (nine minutes). The value of the maxDuration property must be equal to or greater than the value of the timeout property.

Note: You can configure only one value for the timeout and maxDuration properties each, and these values must fit all user actions on all devices.

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 property configurations are ignored and you should only specify the enabled property to avoid confusion:

Groovy Kotlin

desk {
    configurations {
        sampleConfig {
            userActions.enabled false
        }
    }
}

configure<com.desk.tools.android.dsl.DESKExtension> {
    configurations {
        create("sampleConfig") {
            userActions.enabled(false)
        }
    }
}

User action monitoring sensors

The plugin automatically instruments the following listeners and methods:

Android
- android.app.Activity.onOptionsItemSelected
- android.view.MenuItem$OnMenuItemClickListener
- android.view.View$OnClickListener
- android.widget.AdapterView$OnItemClickListener
- android.widget.AdapterView$OnItemSelectedListener
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 properties of UserAction Sensor DSL and configure it inside sensors block:

Groovy Kotlin

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

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

User action naming

For the android.view.View$OnClickListener, android.widget.AdapterView$OnItemClickListener, android.widget.AdapterView$OnItemSelectedListener listeners, OneAgent evaluates the following attributes of the given view in the following order:

content description attribute
text attribute for TextView-based components
class name

For the android.view.MenuItem$OnMenuItemClickListener listener and the android.app.Activity.onOptionsItemSelected method, OneAgent evaluates the title of the given menu item.

For the ViewPager$OnPageChangeListener and SwipeRefreshLayout$OnRefreshListener listeners, no UI component is available, so OneAgent only reports the action type as action name.

Android data binding library

The 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 byte-code and instrument it:

<?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>

Event handler via xml attribute

The following example from the Android documentation shows how an event handler can be defined via xml attributes:

<?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" />

Java Kotlin

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

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

The plugin is unable to 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 successfully 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 DESK Android Gradle plugin can automatically instrument and tag your web requests. To track web requests OneAgent, add the x-desk HTTP header (with a unique value) to the web request. The tag is needed to correlate the server-side monitoring data to the corresponding mobile web request.

Do not manually instrument web requests that are auto-instrumented because it could result in incorrect mobile user experience data.

Configure web request monitoring

All web request monitoring related properties are part of WebRequest DSL and must be configured via the webRequests block:

Groovy Kotlin

desk {
    configurations {
        sampleConfig {
            webRequests {
                // your web request monitoring configuration
            }
        }
    }
}

configure<com.desk.tools.android.dsl.DESKExtension> {
    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 property configurations are ignored and only the enabled property must be specified:

Groovy Kotlin

desk {
    configurations {
        sampleConfig {
            webRequests.enabled false
        }
    }
}

configure<com.desk.tools.android.dsl.DESKExtension> {
    configurations {
        create("sampleConfig") {
            webRequests.enabled(false)
        }
    }
}

Web request monitoring sensors

The following HTTP frameworks are supported:

HttpURLConnection
OkHttp: Only version 3 and 4
Apache HttpClient: Only the Android-internal HttpClient version

Note: Android has deprecated this library (see Android 6.0 changes and Android 9.0 changes) so use a different HTTP framework. The new Apache HttpClient version 5 is not supported. Old Apache HttpClient versions, such as this HttpClient for Android library, are supported because they provide the same interface.

If your web request library is based on one of these supported frameworks, the internal classes of the library are automatically instrumented. For example, Retrofit version 2 is based on OkHttp so all Retrofit web requests are automatically instrumented.

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

Groovy Kotlin

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

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

Lifecycle monitoring

With lifecycle monitoring, OneAgent collects the following data:

Application start event: Calculates the time from Application.onCreate() to Activity.onPostResume() of the first activity. When no activity is displayed at the start of the application, the application-start event is not recorded correctly.
Activity display: Calculates the time from Activity.onCreate(Bundle) to Activity.onPostResume().
Activity redisplay: Calculates the time from Activity.onStart() to Activity.onPostResume().

Configure lifecycle monitoring

These lifecycle events are either part of existing user actions or they create their own display/redisplay action.

All lifecycle monitoring related properties are part of Lifecycle DSL and must be configured via the lifecycle block:

Groovy Kotlin

desk {
    configurations {
        sampleConfig {
            lifecycle {
                // your lifecycle monitoring configuration
            }
        }
    }
}

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

Disable lifecycle monitoring

You can completely deactivate lifecycle monitoring with the enabled property. In this case, all other property configurations are ignored and you must specify the only enabled property:

Groovy Kotlin

desk {
    configurations {
        sampleConfig {
            lifecycle.enabled false
        }
    }
}

configure<com.desk.tools.android.dsl.DESKExtension> {
    configurations {
        create("sampleConfig") {
            lifecycle.enabled(false)
        }
    }
}

Lifecycle monitoring sensors

The plugin automatically instruments the following class:

Android
- android.app.Activity
- android.app.Application
AndroidX
- androidx.fragment.app.Fragment
Android Support
- android.support.v4.app.Fragment

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

Groovy Kotlin

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

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

Support for fragments

The plugin doesn’t support android.app.Fragment because it is already deprecated.

Note: When support for fragments becomes available, it will be activated automatically. If you don’t want fragment monitoring, deactivate the corresponding sensor:

Groovy Kotlin

desk {
    configurations {
        sampleConfig {
            lifecycle {
                sensors {
                    fragment false
                }
            }
        }
    }
}

configure<com.desk.tools.android.dsl.DESKExtension> {
    configurations {
        create("sampleConfig") {
            lifecycle {
                sensors {
                    fragment(false)
                }
            }
        }
    }
}

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 web request is triggered shortly after a monitored user interaction, OneAgent adds the web request as a child event to the monitored user action.

Disable crash reporting

You can deactivate crash reporting with the crashReporting property:

Groovy Kotlin

desk {
    configurations {
        sampleConfig {
            crashReporting false
        }
    }
}

configure<com.desk.tools.android.dsl.DESKExtension> {
    configurations {
        create("sampleConfig") {
            crashReporting(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.

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

Groovy Kotlin

desk {
    configurations {
        sampleConfig {
            locationMonitoring true
        }
    }
}

configure<com.desk.tools.android.dsl.DESKExtension> {
    configurations {
        create("sampleConfig") {
            locationMonitoring(true)
        }
    }
}

OneAgent captures only location data that is already processed in our application. It 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, DESK uses IP addresses to determine the location of the user.

The plugin supports the following location listener:

android.location.LocationListener