Gradle plugin for Android

The Dynatrace Gradle plugin is based on the Android Gradle plugin. It inserts an autoInstrument task into the Android build task sequence. The Dynatrace Gradle plugin lets Android Studio users modify their build.gradle file in a simple way and activate auto-instrumentation with few steps. The Dynatrace Gradle Plugin is hosted on JCenter and Maven Central.

Supported Android Gradle plugin versions

Dynatrace Gradle plugin Required Android Gradle plugin version
7.0.0.2327 - 7.0.0.2429 1.5 - 2.3.3

Note

Version 2.5 of the Android plugin for Gradle contains major changes that break the current Dynatrace Gradle plugin version. See this page for further instructions before you upgrade to the 2.5 version. Instructions are provided once the plugin successfully adapts to the changes.

Configure your build script

Modify your module's build.gradle file to integrate the Dynatrace Gradle plugin into your build task sequence. First, add the remote repository and the Dynatrace Gradle plugin dependency. Then add the dynatrace block with your configuration values.

buildscript {
  repositories {
    jcenter()
  }
  dependencies {
    classpath 'com.dynatrace.tools:android:7.0.+'
  }
}

apply plugin: 'com.dynatrace.tools.android'
dynatrace {
  defaultConfig {
    applicationId 'MyExampleAppID'
    startupPath 'https://dev.example.com:443'
  }
}

The minimal configuration must contain the applicationId and the startupPath value. Specify a unique application ID with the applicationId property, and specify the instrumented web or application server address with the startupPath property.

Customize auto-instrumentation properties

Use the auto-instrumentation properties to customize your auto-instrumentation process. Set these auto-instrumentation properties with the agentProperties plugin property. The property syntax is a key-value list, where the elements are separated by a comma and the key-value pair is separated by a colon. For example:

dynatrace {
  defaultConfig {
    applicationId 'MyExampleAppID'
    startupPath 'https://dev.example.com:443'
    agentProperties 'DTXSendEmptyAutoAction': 'true', 'DTXLogLevel': 'debug'
  }
}

Combine with manual instrumentation

Add the Dynatrace OneAgent library with the Dynatrace Gradle plugin to use a combination of manual and auto-instrumentation to monitor your application. This allows you to automatically update the OneAgent library with the Gradle plugin, and ensures that the OneAgent library and the auto-instrumentation have the same version. To enable the manual instrumentation, add the dynatrace.agent() dependency. For example:

dependencies {
  compile dynatrace.agent()
}

Note

Do not obfuscate or optimize the Dynatrace agent library. See ProGuard configuration) for more information.

For multi-dex applications, ensure all agent classes are in the primary .dex file. Use the multiDexKeepProguard Android plugin property and add the line -keep class com.dynatrace.android.** { *; } to the provided file. For example:

buildTypes {
  release {
    multiDexKeepProguard file('<your_keep_file>')
  }
}

Use different product flavor configurations

If you use different product flavors, you can also specify different configurations for the auto-instrumentation task. For every product flavor the Gradle plugin checks if you've specified a configuration in the productFlavors block of the dynatrace block. If no configuration is available, the defaultConfig configuration is used.

dynatrace {
  defaultConfig {
    applicationId 'MyDefaultAppID'
    startupPath 'https://dev.example.com:443'
  }

  productFlavors {
    prod {
      applicationId 'MyProdAppID'
      startupPath 'https://prod.example.com:443'
    }
  }
}

Use a Gradle property to deactivate instrumentation

Currently there is no option to deactivate the plugin dynamically. Use a Gradle property to activate or deactivate the plugin. For example:

if(project.hasProperty('instrument')) {
  apply plugin: 'com.dynatrace.tools.android'
  dynatrace {
    defaultConfig {
      applicationId 'MyExampleAppID'
      startupPath 'https://dev.example.com:443'
    }
  }
}

You can activate the Dynatrace Gradle plugin by adding the -Pinstrument parameter to your build command. If you want to build an instrumented release version, execute the gradlew assembleRelease -Pinstrument command.

Signing

The Dynatrace Gradle plugin uses the signing configuration and logic from the Android Gradle plugin. You do not have to add any additional settings to the Dynatrace Gradle plugin.

android {
    ...
    defaultConfig {  }
    signingConfigs {
        release {
            storeFile file("my-release-key.jks")
            storePassword "password"
            keyAlias "my-alias"
            keyPassword "password"
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
            ...
        }
    }
}

The Dynatrace Gradle plugin stores the instrumented and signed app under the same name in the same location (<project>/<module>/build/outputs/apk/<app_name>.apk). The advantage of this approach is that the Run button from Android Studio can use the instrumented APK file and can install it on your device/emulator.

Optimizations

The auto-instrumentor must execute some preparation steps before instrumenting your APK file. You can reduce auto-instrumentation execution time by generating an adjusted APK file. This lets the auto-instrumentor skip some of the preparation steps and reduce the execution time. This optimization options are optional, because the auto-instrumentor has a built-in logic to execute similar steps.

You can set the jumbo mode option in the Android Gradle plugin to skip the internal auto-instrumentor step string identifier adaption. For example:

dexOptions {
  jumboMode true
}

This option reduces the auto-instrumentation execution time for multidex apps (and apps exceeding the 64K string identifier border).

For multi-dex application the auto-instrumentor has to ensure there is enough space for the agent in the primary .dex file. To do this, it moves some classes from the primary .dex file into another .dex file. You can skip this step, if you generate a primary .dex file that has enough space for the agent. You can archive this by using the -&dash;minimal-main-dex or -&dash;set-max-idx-number option of the Android Gradle plugin. See the Multi-dex applications section in Auto-instrumentation for Android for more information.

Limitations

  • Do NOT use whitespaces in your project path.
  • Do NOT use the Android Studio feature Instant Run.

See the Auto-instrumentation limitations for more information.

Instant Run

With Android Studio 2.0, Android introduced the new feature Instant Run. This feature significantly reduces the app update time. The Dynatrace Gradle plugin for Android does not support Instant Run APKs and the corresponding Gradle build process. You should disable the Instant Run setting. To do this, open the Settings and navigate to Build, Execution, Deployment > Instant Run. Then clear the Enable Instant Run check box.