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.3.1019 1.5 - 2.3.3
7.0.5.1020 - 7.0.17.1015 1.5 - 3.0.1
7.0.18.1007 - 7.0.22.1015 1.5 - 3.1
7.1.0.2116 - 7.1.4.2244 1.5 - 3.1

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.1.+'
  }
}

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.

If the compileSdkVersion setting in your build.gradle file is 23 (Android 6.0) or later, then you must add the compile-time dependency for the Apache HTTP client library as descripted in the manual instrumentation documentation.

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.

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.