Dynatrace Android Gradle plugin

You can use the Dynatrace Android Gradle plugin only for Android projects that use the Android Gradle plugin to build the app. You should apply the Dynatrace Android Gradle to the top-level build file (either build.gradle or build.gradle.kts), which is located in the root project directory. This approach allows the plugin to properly configure the Android subprojects and establish the auto-instrumentation process as part of the Android build process.

The Dynatrace Android Gradle plugin is hosted on Maven Central, and the technical documentation is available as DSL reference.

In a couple of months, we'll stop setting cookies to file scheme domains for hybrid applications. See Disable cookies for file domains for more details and action items.

Jetpack Compose auto-instrumentation is enabled by default starting with Dynatrace Android Gradle plugin version 8.271.

Requirements

  • Gradle version 7.0.2+
  • Android Gradle plugin version 7.0+
  • JVM: Java 11+

Instrumentation

The Dynatrace Android Gradle plugin uses bytecode instrumentation to instrument your app. It can instrument the source files of all subprojects and third-party libraries. Performance-wise, bytecode instrumentation is quick and has a low impact on the build time. By providing support for incremental builds and the build cache, the instrumentation of apps will be almost unnoticed.

Instrumentation-specific capabilities

  • Java and Kotlin: The Dynatrace Android Gradle plugin supports the instrumentation of Java and Kotlin classes. It also supports other JVM languages.

  • Obfuscations and optimization: The auto-instrumentation process is completed before the R8 Gradle task. If you use another tool for obfuscation, you must ensure that the obfuscation task is executed after the auto-instrumentation process.

  • Security and APK-hardening tools: Bytecode instrumentation happens before obfuscation and before Android Dexer (D8) transforms the .class bytecode into .dex bytecode that can be executed in the Android Runtime. Therefore, the plugin can ensure maximum compatibility with other security-focused and APK-hardening tools that calculate checksums for the DEX code, such as DexGuard and Arxan.

Instrumentation-specific limitations

The Android Gradle plugin only instruments the AndroidManifest.xml and other .class files. It doesn’t instrument the following components:

  • Native code, such as code written with the NDK
  • Web components, such as .html and .js files
  • Resource files, such as layout .xml files

Compatibility with other monitoring tools

There might be compatibility issues with other performance monitoring plugins, especially when these plugins instrument OneAgent for Android. We recommend either using only one performance monitoring plugin or verifying via manual testing that the plugins you've chosen are compatible.

Build

Build-specific capabilities

The Dynatrace Android Gradle plugin supports Gradle build-specific capabilities, including the following:

  • Faster incremental builds by modifying only classes and libraries, thereby reducing instrumentation time.
  • Build cache to reduce build time by reusing outputs produced by other builds.
  • Dynatrace Android Gradle plugin version 8.257+ Configuration cache to reduce build time by reusing the cached result of the configuration phase.
  • Apply Changes for pushing code and resource changes to a running app without having to restart it. The app must be restarted only when the configuration of the plugin or OneAgent is changed.
  • Build processes for Android App Bundles and APKs.
  • Multiple APK builds via the splits block so that the instrumentation step is executed only once.
  • Support for Kotlin DSL in build.gradle.kts files.

Build-specific limitations

  • Android library projects: The Dynatrace Android Gradle plugin auto-instruments only Android application projects. It doesn't support the auto-instrumentation of stand-alone Android library projects. Our plugin auto-instruments the internal libraries if you add them as a dependency to your Android application project.
  • Android Gradle plugin excludes property: With the excludes property of the Android Gradle plugin, you can disable instrumentation for specific classes. This property is similar to the exclude property of the Dynatrace Android Gradle plugin. However, when you use the Dynatrace property, our plugin still instruments some very important classes to ensure that instrumentation is always valid. With the Android excludes property, all the specified classes aren't instrumented, which might negatively affect the instrumentation.

Configuration

The Android Gradle plugin provides a wide range of configuration options to customize your Android application build and the monitored mobile user experience data.

The Gradle snippet from the Instrumentation page and the Gradle snippets from the documentation contain sample names for variant-specific configuration, such as sampleConfig. To understand this better, see how variant-specific configurations are used.

Configure monitoring capabilities

The following options can be used to customize OneAgent SDK for Android monitoring capabilities and fine-tune the auto-instrumentation process.

Configure instrumentation processes

The plugin also provides additional configuration options to customize the instrumentation process:

Adjust OneAgent configuration

The following configuration options can be used to adjust the default OneAgent configuration:

These options are especially helpful when used along with the automatic OneAgent startup. They can also be used to adjust the OneAgent configuration when approached with the manual startup, but you need to be careful because the settings can easily be overridden with ConfigurationBuilder.

Adjust Dynatrace Android Gradle plugin configuration based on the project structure

Our plugin scans all subprojects and configures the auto-instrumentation process for your application modules. Other modules are unaffected by the plugin. In this case, you might need to adjust the instrumentation process for an Android project with: