Header background

Announcing new and super fast Android auto-instrumentation (Preview)

We’re proud to announce the Preview of our new and super fast Android auto-instrumentation. We’ve been working on the new instrumentation approach for the past 6 months and have effectively reinvented it, making it easier to integrate, more compatible, and super fast. With the new auto-instrumentor, monitoring of your Android apps will be more fun than ever before.

Why we changed our approach to Android instrumentation

The current Android auto-instrumentation approach is based on DEX file modification. This is a versatile approach as it allows anyone to instrument an APK, even those who don’t have access to the development environment. We’ve had many successes with customers and prospects where we simply downloaded their APK from the Play Store and instrumented it via the command line. It only took about 15 minutes to set up this approach with Dynatrace and get detailed insights into Android app performance.

However, besides the benefits, we also encountered some flaws with the current approach. That’s why we’ve reinvented auto-instrumentation once again. Our goal has been to keep all the benefits while addressing the flaws, which are listed below.

Topic Description
Previous auto-instrumentation New auto-instrumentation
Support for complex build environments Many of our customers have complex app-builds with different flavors and build types that require variations in how OneAgent for Android is configured.
  • The previous Gradle plugin had limitations in supporting build variants.
  • The new Gradle plugin allows you to specify individual configurations for build variants.
Compatibility with other technologies This includes support for multi-dex apps, security and obfuscation tools, and support for new features like AppBundles, etc.
  • Configuration was required for support of obfuscation. Certain security tools like DexGuard weren’t fully supported.
  • Instrumenting multi-dex apps sometimes required advanced manual fine-tuning.
  • Adding support for AppBundles was possible, but non-trivial.
  • The new auto-instrumentation runs before obfuscation and the dex-transformation takes place.
  • No multi-dex issues
  • Maximum compatibility with obfuscation and security tools.
  • Out-of-the-box support for AppBundles.
Build performance If you want to include Dynatrace in development and staging builds, build performance is crucial.
  • Auto-instrumentation took several minutes. The plugin didn’t support incremental builds. Moreover, features like Instant Run and the Gradle Build Cache weren’t supported.
  • Out-of-the-box support for Instant Run and the Gradle Build Cache make the auto-instrumentation process barely noticeable.
Supportability As a bonus, we also want to reduce the effort that’s necessary to support new Android versions.
  • The DEX-file modification framework was abandoned by its original authors which resulted in a high maintenance effort for us.
  • For bytecode instrumentation, we rely on a well-tested framework that’s also the foundation of the OneAgent Java module.

The new Android auto-instrumentation

We’ve updated and improved the following three components that make up OneAgent for Android:

  • A brand new Gradle plugin that provides many new configuration possibilities and integrates auto-instrumentation perfectly into complex Android Studio projects
  • The new bytecode based Auto-instrumentor weaves in OneAgent for Android at build time
  • The new version of OneAgent for Android addresses several small inconsistencies

Gradle plugin

Let’s take a look at the new Gradle plugin first. Based on the feedback that we received from our customers, we developed a flexible DSL that allows you to maintain separate configurations for build variants. This allows you to configure a different application endpoint for your staging builds or to turn off instrumentation completely for a certain development build. All auto-instrumentation settings are available as Gradle configuration properties. To understand the new capabilities, have a look at the examples below.

Gradle example 1

Example 1 shows the most basic configuration. It contains a single block called sampleConfig, which instruments apps using the default settings.

Gradle example 2

Example 2 contains 3 configuration blocks:

  • The first one (dev) disables the instrumentation for development builds by matching it to the build type debug.
  • The second one (demo) matches the demo flavor, which is defined in the Gradle script and disables web request monitoring.
  • The third one matches the production version (i.e., the “paid” flavor). It disables the auto-start feature. If auto-start is disabled, you don’t have to provide the applicationId and the beaconUrl. Instead, you have to provide theses programmatically once you call the startup method in your app code. This comes in handy if you want to dynamically decide where to send your monitoring data. Additionally, the userOptIn mode gets enabled, which means that your users can decide what details they want to share with you.

As you can see, each configuration block can contain a variant filter that will be evaluated as regex on the current build variant. You can also specify one block without a variant filter, which matches all build variants. The order of your configuration blocks is important as the first matching block is used.

Let’s run the build for the sample above…

Failing Android build

The build failed because no matching configuration was found for the build variant PaidDebug. This behavior can be controlled via the strictMode setting at the beginning of the dynatrace-block. The default for this setting is true. By changing it to false, we can run the build again and it will succeed, but the Dynatrace Gradle plugin won’t be executed.

Let’s review what configuration will be used for the different build variants. The printVariantAffiliation task lists all possible build variants and displays which configuration will be used. In our example, it shows that the PaidDebug variant doesn’t have a matching Dynatrace configuration. While reviewing our Gradle file you’ll notice that we misspelled “Debug”. After fixing the typo, we can run the build again and it will succeed.

The printVariantAffiliation task

To understand the full set of capabilities of the new Dynatrace Gradle plugin, you should review the DSL documentation that is contained in the Preview bundle, which you will receive, once you’ve registered for the Preview.

There are some other cool features that the Gradle plugin supports to help you save time:

  1. Gradle build cache support: this allows your build to fetch outputs from a local or remote cache when it’s determined that inputs haven’t changed
  2. Instant run and incremental build support: you can now use the Instant run feature during development time
  3. Full support for Groovy and Kotlin Gradle files

Auto-instrumentor

The new Auto-instrumentor uses bytecode instrumentation to instrument your app. It relies on ASM, which is widely used and well maintained, so all Java language features can be supported. We also implemented thousands of test cases and run them with every build to ensure the best compatibility with all customer apps.

Bytecode instrumentation takes place before obfuscation and also before the Android Dexer (D8) transforms the CLASS bytecode into DEX bytecode that can be executed in the Android Runtime. This means that we can also ensure maximum compatibility with obfuscation tools, as well as any other security-focused tools that calculate checksums for the DEX code, for example, DexGuard.

Performance-wise, bytecode instrumentation is a fast process that doesn’t impact build time. With the previous approach of unpacking the APK, instrumenting the DEX code, packing the APK, and signing it for a second time took time to complete. The new approach is complete in seconds. Combined with incremental build support and build caching, you’ll hardly notice that you’re instrumenting your apps.

OneAgent for Android

We also made some minor API improvements along the way that provide you with a more consistent Android SDK, most notably, we removed the deprecated manual startup API of OneAgent for Android that was replaced with an easy-to-use builder API, as well as the removal of unnecessary response codes from the API.

How do I get started?

The new Gradle plugin requires you to use at least Gradle 5.0 and the Android Gradle plugin 3.1. During the Preview phase, we’re only supporting plain Android apps that are written in Java or Kotlin (no hybrid frameworks). If your app meets these requirements, please register using the Preview signup form.

Once you’re signed up, we will email you the download link for the Preview bundle that contains the Gradle plugin and the new OneAgent for Android, a sample project, and the DSL documentation for the Gradle plugin so you can get started right away. There are no additional dependencies on your cluster version.

Summary

The new Android auto-instrumentor will make your life easier and save you a lot of build time. It also serves as a good foundation for us to add support for new Android features and drive innovation around mobile monitoring.