UI Breadcrumbs for Android Error Events

In [many] cases, when a crash happens in your Android application, you want more context on what occurred before the issue — kind of like following breadcrumbs to the exception. Our SDKs automatically report breadcrumbs for activity lifecycle events, system events, HTTP requests, and many more. Now, Android developers will also see UI events listed as breadcrumbs and get the full picture of what happened without ever having to recreate the issue.

What are Breadcrumbs?

Breadcrumbs are the trail of events that your user fired prior to experiencing the error. These events can be as simple as generic logging messages. But, they can also contain rich metadata about the state of your application: network requests, database queries, UI events, navigation changes, or even earlier occurring errors.

Breadcrumbs can be incredibly helpful in reproducing the steps that led to the error you’re debugging. We’ve been dogfooding them at Sentry for some time at this point, and they add critical context to errors that a stack trace alone can’t provide.

Automated UI Breadcrumbs

To get started with automated breadcrumbs capturing for UI events, make sure to use Sentry Android SDK version 5.6.0 or above:

// Make sure mavenCentral is there.
repositories {
    mavenCentral()
}

dependencies {
    implementation 'io.sentry:sentry-android:5.6.0'
}

Once the SDK is installed, it will start automatically capturing breadcrumbs for different UI events (clicks, scrolls, swipes, etc.), as the integration is enabled by default.

Verify

Now, when your application crashes — in addition to already existing breadcrumbs — you also will see the trace of UI events that happened prior to the crash event.It’ll look similar to this:

When we record breadcrumbs, we capture some useful metadata of the target view; information like view id, view class, and scroll direction (in case the view is scrollable). This can help tremendously in understanding the root cause of an issue because you can analyze and even reproduce user actions prior to the crash event.

R8/Proguard

If you’re using R8/Proguard for minifying your application, the view class might be obfuscated, depending on where it comes from. Standard Android SDK views will not be obfuscated, whereas Jetpack/AndroidX views will be. This behavior can be customized through BeforeBreadcrumbCallback as follows:

SentryAndroid.init(this) { options ->
    options.beforeBreadcrumb = SentryOptions.BeforeBreadcrumbCallback { breadcrumb, _ ->
        if (breadcrumb.category?.startsWith("ui.") == true) {
            val viewId = breadcrumb.getData("view.id")
            if (viewId is String) {
                val id = resources.getIdentifier(viewId, "id", packageName)
                val viewClass = when(id) {
                    R.id.lyrics -> "TextView"
                    R.id.edit_track -> "Button"
                    else -> "undefined"
                }
                breadcrumb.setData("view.class", viewClass)
            }
        }
        breadcrumb
    }
}

Here, we check that the breadcrumb is of the UI category, retrieve the supplied viewId, convert it to an integer, and map that using the R class to an appropriate view class name.

Disable UI breadcrumbs

If you wish to disable the automated collection of UI breadcrumbs, Sentry exposes a configuration option through the Android manifest:

<application>
   <!-- To disable the user interaction breadcrumbs integration -->
    <meta-data android:name="io.sentry.breadcrumbs.user-interaction" android:value="false" />
</application>

Use Automated Breadcrumbs for UI Events

Most of our client SDKs already support automated breadcrumbs for UI events. Check out our docs for iOS, React Native, Dart, JavaScript, Native, and Xamarin for more details.