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

  • ProGuard/R8 mappings upload
  • Native debug symbols and sources upload
  • Auto-instrumentation
    tracingThe process of logging the events that took place during a request, often across multiple services.
    through bytecode manipulation
  • Logcat breadcrumb logging
  • Auto-installation of the Sentry Android SDK and its integrations
  • External dependencies report

Setup

Install

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

app/build.gradle
Copied
buildscript {
    repositories {
        mavenCentral()
    }
}

plugins {
    id "com.android.application"
    id "io.sentry.android.gradle" version "3.5.0"
}

Configure

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 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.
    experimentalGuardsquareSupport = 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

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

    // 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 = '6.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
}

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 & DexGuard

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.

If you are using the Guardsquare's ProGuard or DexGuard tooling, you have to enable the experimentalGuardsquareSupport flag.

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,

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

Auto-Installation

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!) to suggesting an update ("yeah, this would be better").