Gradle

Learn about using the Sentry Android Gradle Plugin.

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 following features:

  • ProGuard/R8 mappings upload
  • Java/Kotlin Source Context upload
  • Native debug symbols and sources upload
  • Auto-instrumentation tracing through bytecode manipulation
  • Logcat breadcrumb logging
  • Auto-installation of the Sentry Android SDK and its integrations
  • External dependencies report

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

app/build.gradle
Copied
plugins {
    id "com.android.application"
    id "io.sentry.android.gradle" version "4.14.1"
}

The io.sentry.android.gradle >= 3.0.0 requires Android Gradle Plugin >= 7.0.0. For older versions of the Android Gradle Plugin, use io.sentry.android.gradle:2.+.

Set the auth token as an environment variable to be used when running your release build.

Copied
export SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE

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

Copied
import io.sentry.android.gradle.extensions.InstrumentationFeature
import io.sentry.android.gradle.instrumentation.logcat.LogcatLevel

sentry {
    // Disables or enables debug log output, e.g. for for sentry-cli.
    // Default is disabled.
    debug = false

    // The slug of the Sentry organization to use for uploading proguard mappings/source contexts.
    org = "example-org"

    // The slug of the Sentry project to use for uploading proguard mappings/source contexts.
    projectName = "example-project"

    // The authentication token to use for uploading proguard mappings/source contexts.
    // WARNING: Do not expose this token in your build.gradle files, but rather set an environment
    // variable and read it into this property.
    authToken = System.getenv("SENTRY_AUTH_TOKEN")

    // The url of your Sentry instance. If you're using SAAS (not self hosting) you do not have to
    // set this. If you are self hosting you can set your URL here
    url = null

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

    // Experimental flag to turn on support for GuardSquare's tools integration (Dexguard and External Proguard).
    // If enabled, the plugin will try to consume and upload the mapping file produced by Dexguard and External Proguard.
    // Default is disabled.
    dexguardEnabled = false

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

    // Whether the plugin should attempt to auto-upload the native debug symbols to Sentry or not.
    // If disabled the plugin will run a dry-run.
    // Default is enabled.
    autoUploadNativeSymbols = true

    // 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.
    // This option has an effect only when [uploadNativeSymbols] is enabled.
    // Default is disabled.
    includeNativeSources = false

    // Generates a JVM (Java, Kotlin, etc.) source bundle and uploads your source code to Sentry.
    // This enables source context, allowing you to see your source
    // code as part of your stack traces in Sentry.
    includeSourceContext = false

    // Configure additional directories to be included in the source bundle which is used for
    // source context. The directories should be specified relative to the Gradle module/project's
    // root. For example, if you have a custom source set alongside 'main', the parameter would be
    // 'src/custom/java'.
    additionalSourceDirsForSourceContext = []

    // Enable or disable the tracing instrumentation.
    // Does auto instrumentation for specified features through bytecode manipulation.
    // Default is enabled.
    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, InstrumentationFeature.OKHTTP, InstrumentationFeature.COMPOSE]

      // Enable or disable logcat instrumentation through bytecode manipulation.
      // Default is enabled.
      logcat {
        enabled = true

        // Specifies a minimum log level for the logcat breadcrumb logging.
        // Defaults to LogcatLevel.WARNING.
        minLevel = LogcatLevel.WARNING
      }

      // The set of glob patterns to exclude from instrumentation. Classes matching any of these
      // patterns in the project's sources and dependencies JARs won't be instrumented by the Sentry
      // Gradle plugin.
      //
      // Don't include the file extension. Filtering is done on compiled classes and
      // the .class suffix isn't included in the pattern matching.
      //
      // Example usage:
      // ```
      // excludes = ['com/example/donotinstrument/**', '**/*Test']
      // ```
      //
      // Only supported when using Android Gradle plugin (AGP) version 7.4.0 and above.
      excludes = []
    }

    // Enable auto-installation of Sentry components (sentry-android SDK and okhttp, timber and fragment integrations).
    // Default is enabled.
    // Only available v3.1.0 and above.
    autoInstallation {
      enabled = true

      // Specifies a version of the sentry-android SDK and fragment, timber and okhttp integrations.
      //
      // This is also useful, when you have the sentry-android SDK already included into a transitive dependency/module and want to
      // align integration versions with it (if it's a direct dependency, the version will be inferred).
      //
      // NOTE: if you have a higher version of the sentry-android SDK or integrations on the classpath, this setting will have no effect
      // as Gradle will resolve it to the latest version.
      //
      // Defaults to the latest published Sentry version.
      sentryVersion = '7.18.1'
    }

    // Disables or enables dependencies metadata reporting for Sentry.
    // If enabled, the plugin will collect external dependencies and
    // upload them to Sentry as part of events. If disabled, all the logic
    // related to the dependencies metadata report will be excluded.
    //
    // Default is enabled.
    includeDependenciesReport = true

    // Whether the plugin should send telemetry data to Sentry.
    // If disabled the plugin won't send telemetry data.
    // This is auto disabled if running against a self hosted instance of Sentry.
    // Default is enabled.
    telemetry = true
}

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.

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"]
}

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 as long as you've enabled ProGuard/R8. The credentials for the upload step are defined in the Gradle extension above or loaded from a sentry.properties file in your project.

To use Guardsquare's ProGuard or DexGuard tooling, you'll have to enable the dexguardEnabled flag. Learn more in the full sentry-cli documentation.

Instead of providing your credentials via the Gradle extension, you can create a sentry.properties file with the following content under your app module:

Copied
defaults.project=example-project
defaults.org=example-org
auth.token=sntrys_YOUR_TOKEN_HERE

You can find your authentication token on the Organization Auth Tokens settings page. For more information about the available configuration options, check out the full sentry-cli documentation.

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=example-project
defaults.org=example-org
auth.token=sntrys_YOUR_TOKEN_HERE

You can find your authentication token on the Sentry API page. For more information about the available configuration options, check out the full sentry-cli documentation.

This plugin can automatically upload your source code to Sentry so it is shown as part of the stack traces.

Copied
sentry {
    includeSourceContext = true
}

Checkout the full documentation on Source Context for more details.

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.

For this data to be captured, you must enable tracing.

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,

    /**
     * When enabled the SDK will create spans for outgoing network requests and attach
     * sentry-trace-header for distributed tracing.
     * This feature uses bytecode manipulation and attaches SentryOkHttpInterceptor to all OkHttp
     * clients in the project.
     *
     * Requires sentry-android SDK version 5.0.0 and above.
     * Only available v3.1.0 and above of the Sentry Android Gradle plugin.
     */
    OKHTTP,

    /**
     * When enabled the SDK will create breadcrumbs when navigating
     * using [androidx.navigation.NavController].
     * This feature uses bytecode manipulation and adds an OnDestinationChangedListener to all
     * navigation controllers used in Jetpack Compose.
     */
    COMPOSE
}

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

To learn more about the internals of auto-instrumentation, check out this blog post.

The plugin offers the automated installation feature of the Sentry Android SDK and the Fragment, Timber, OkHttp, and Jetpack Compose integrations. Starting with version 3.1.0, the feature is enabled by default, so you don't need to add any dependencies — you just use the Sentry Gradle plugin.

The plugin algorithm does the following when defining dependency versions:

  1. Check if the module/app has a direct dependency on the Sentry Android SDK:

    • If yes, then use the version of the direct dependency.

    • If no, then automatically add the sentry-android dependency with the specified sentryVersion from the plugin configuration (defaults to the latest published SDK version).

  2. Check if the module/app has a direct dependency on any of the integrations (Fragment, Timber, or OkHttp):

    • If yes, then keep the current version of the direct dependency.

    • If no, then automatically add the integration dependency with the version of the Sentry Android SDK inferred from above.

  3. If there are transitive dependencies on any of the integrations or the Sentry Android SDK, then their versions are not considered. However, if the versions are higher than those bundled with the Sentry Gradle plugin, Gradle will choose them instead.

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