Gradle

The Sentry Android Gradle Plugin is an addition to the main Android and Hybrid SDKs (like React Native and Flutter) and offers seamless integration with the Gradle build system. It supports the upload of ProGuard/R8 mappings and of Native debug symbols and sources, as well as auto-instrumentation tracing through bytecode manipulation.

Setup

Install

Using Gradle (Android Studio) in your app/build.gradle add:

Copied
buildscript {
    repositories {
        mavenCentral()
    }
}

plugins {
    id "io.sentry.android.gradle" version "2.1.5"
}

Configure

We expose the following configuration values directly in your app/build.gradle:

Copied
import io.sentry.android.gradle.InstrumentationFeature

sentry {
    // Disables or enables the handling of Proguard mapping for Sentry.
    // If enabled the plugin will generate a UUID and will take care of
    // uploading the mapping to Sentry. If disabled, all the logic
    // related to proguard mapping will be excluded.
    // Default is enabled.
    includeProguardMapping = true

    // Whether the plugin should attempt to auto-upload the mapping file to Sentry or not.
    // If disabled the plugin will run a dry-run and just generate a UUID.
    // The mapping file has to be uploaded manually via sentry-cli in this case.
    // Default is enabled.
    autoUploadProguardMapping = true

    // Disables or enables the automatic configuration of Native Symbols
    // for Sentry. This executes sentry-cli automatically so
    // you don't need to do it manually.
    // Default is disabled.
    uploadNativeSymbols = false

    // Does or doesn't include the source code of native code for Sentry.
    // This executes sentry-cli with the --include-sources param. automatically so
    // you don't need to do it manually.
    // Default is disabled.
    includeNativeSources = false

    // Enable or disable the tracing instrumentation.
    // Does auto instrumentation for specified features through bytecode manipulation.
    // Default is enabled.
    // Only available v3.0.0 and above.
    tracingInstrumentation {
      enabled = true

      // Specifies a set of instrumentation features that are eligible for bytecode manipulation.
      // Defaults to all available values of InstrumentationFeature enum class.
      features = [InstrumentationFeature.DATABASE, InstrumentationFeature.FILE_IO]
    }
}

Now when you build your app, the plugin will upload the ProGuard/R8 mappings, source bundle, and native symbols as you configured them to Sentry.

Variant Filtering

You can specify which variant/flavor/build-type should be ignored by Sentry in your app/build.gradle file:

Copied
sentry {
    // List the build types that should be ignored (e.g. "release").
    ignoredBuildTypes = ["release"]

    // List the build flavors that should be ignored (e.g. "production").
    ignoredFlavors = ["production"]

    // List the build variant that should be ignored (e.g. "productionRelease").
    ignoredVariants = ["productionRelease"]
}

ProGuard/R8

The plugin will automatically generate appropriate ProGuard mapping files and upload them when you run gradle assemble{BuildVariant}. For example, assembleRelease — Release is the default, but the plugin works for others if you have enabled ProGuard/R8. The credentials for the upload step are loaded through environment variables or from a sentry.properties file in your project root.

Learn more in the full sentry-cli documentation.

At the very minimum, you will need something similar to:

Copied
defaults.project=your-project
defaults.org=your-org
auth.token=YOUR_AUTH_TOKEN

Native Debug Symbols and Sources

The plugin will automatically discover and upload Native debug symbols and sources when you run gradle assemble{BuildVariant}. The {BuildVariant} must be a non-debuggable build type, for example Release. The credentials for the upload step are loaded via environment variables or from a sentry.properties file in your project root.

Learn more in the full sentry-cli documentation.

At the very minimum, you will need something similar to:

Copied
defaults.project=your-project
defaults.org=your-org
auth.token=YOUR_AUTH_TOKEN

Tracing Auto-instrumentation

The plugin uses the bytecode manipulation framework to inject a code snippet that starts and finishes a span for common operations that can cause performance bottlenecks. This way potentially heavy operations are automatically measured without the need to manually instrument them.

The plugin supports the following features for auto-instrumentation:

Copied
enum class InstrumentationFeature {
    /**
     * When enabled the SDK will create spans for any CRUD operation performed by 'androidx.sqlite'
     * and 'androidx.room'. This feature uses bytecode manipulation.
     *
     * Requires sentry-android SDK version 4.0.0 and above
     */
    DATABASE,

    /**
     * When enabled the SDK will create spans for [java.io.FileInputStream],
     * [java.io.FileOutputStream], [java.io.FileReader], [java.io.FileWriter].
     * This feature uses bytecode manipulation and replaces the above
     * mentioned classes with Sentry-specific implementations.
     *
     * Requires sentry-android SDK version 5.5.0 and above
     */
    FILE_IO
}

Check Integrations page for more detailed explanation of each instrumentation feature.

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").