Configure Android Gradle plugin for instrumentation process

Version 8.x

This is documentation for the most recent version 8.x. It is only supported for AppMon 2018 October.

If you're using older version, see Android Agent 7.x.

The following configuration options allow you to customize the instrumentation process of the Dynatrace Android Gradle plugin.

Variant-specific configurations

The plugin allows you to specify multiple variant-specific configurations, where each variant-specific configuration can be applied to multiple Android build variants. You must provide a variant-specific configuration for every variant. If the plugin is unable to find a variant-specific configuration for a certain Android build variant, it cancels the build and throws an error. This protection feature can be deactivated with the strictMode property.

The association is determined by the regex, that is specified in the variantFilter property, and the variant name of the Android build variant. The regex is case-sensitive and if no product flavor is defined, the build type in the variant name is lower case. If multiple variant-specific configurations match the same variant, the first configuration is selected and applied.

The following sample shows how you can specify a variant-specific configuration in the dynatrace block:

Download
dynatrace {
    configurations {
        dev {
            // build type name is upper case because a product flavor is used
            variantFilter "Debug"
            // other variant-specific properties
        }
        demo {
            // the first product flavor name is always lower case
            variantFilter "demo"
            // other variant-specific properties
        }
        prod {
            // build type name is upper case because a product flavor is used
            variantFilter "Release"
            // other variant-specific properties
        }
    }
}

For example, you can have an app that has two product flavors, demo and paid, and two default build types, debug and release. The plugin can be used to specify a variant-specific configuration for all debug build variants, demoDebug and paidDemo, and another two variant-specific configurations for the two variants, demoRelease and paidRelease.

The association between variant-specific configurations from the plugin and the Android build variants can be printed with the printVariantAffiliation task. For example, the following sample shows the console output of the above example:

> Task :app:printVariantAffiliation
Variant 'demoDebug' will use configuration 'dev'
Variant 'demoRelease' will use configuration 'demo'
Variant 'paidDebug' will use configuration 'dev'
Variant 'paidRelease' will use configuration 'prod'

Separate development and production monitoring data

If you don't want to pollute your production monitoring data with monitoring data from your debug builds, separate the development data from the production monitoring data.

To do this, create two mobile apps. Generate two variant-specific configurations and use the correct applicationId and agentPath values from your debug and production environment.

Download
dynatrace {
    configurations {
        debug {
            variantFilter "[dD]ebug"
            autoStart {
                applicationId '<DebugApplicationID>'
                agentPath '<DebugAgentPathUrl>'
            }
        }
        prod {
            variantFilter "[rR]elease"
            autoStart {
                applicationId '<ProductionApplicationID>'
                agentPath '<ProductionAgentPathUrl>'
            }
        }
    }
}

If you prefer to not monitor your debug builds, disable the variant-specific configuration that is responsible for your debug builds.

Download
dynatrace {
    configurations {
        debug {
            variantFilter "[dD]ebug"
            enabled false
        }
        prod {
            variantFilter "[rR]elease"
            autoStart {
                applicationId '<ProductionApplicationID>'
                agentPath '<ProductionAgentPathUrl>'
            }
        }
    }
}

Deactivate auto-instrumentation

You can deactivate auto-instrumentation for all variants or for a specific variant.

Deactivate all variants

To deactivate auto-instrumentation for all variants, deactivate the plugin with the pluginEnabled property. The plugin still adds Android Agent SDK as Gradle dependency to ensure that the compiler can compile the manually instrumented source files.

With this setting, the verification step of the plugin is deactivated. Also, the auto-start feature is deactivated and the app stops being monitored. If you start the agent manually, the app is monitored, but the Agent can capture only mobile user experience data that is instrumented by manual calls to the Android Agent SDK.

You can deactivate auto-instrumentation for all variants or for a specific variant.

Download
dynatrace {
    pluginEnabled false
    configurations {
        dev {
            // variant-specific properties
        }
        prod {
            // variant-specific properties
        }
    }
}

Deactivate one variant

If you want to deactivate auto-instrumentation for a specific variant, explicitly deactivate the variant-specific configuration via the enabled property. The following example shows how you can deactivate all debug build types (variant demoDebug and paidDebug):

Download
dynatrace {
    configurations {
        dev {
            enabled false
            variantFilter "Debug"
        }
        prod {
            // variant-specific properties
        }
    }
}

Skip auto-instrumentation when no variant-specific configuration is available

You can deactivate the strictMode property and only define a variant-specific configuration for the variant you want to instrument. The plugin doesn’t instrument Android build variants when no variant-specific configuration matches the given Android build variant.

If you don't deactivate the strictMode property, the plugin cancels the build and throws an error. We don't recommend this approach, because the strict mode feature should protect you from building variants with no variant-specific configuration. Deactivate auto-instrumentation via the enabled property of your variant-specific configuration.

Download
dynatrace {
    strictMode false
    configurations {
        prod {
            variantFilter "Release"
            // other variant-specific properties
        }
    }
}

Auto-start injection

To obtain the correct startup parameters, go to the Dynatrace Instrumentation page of your mobile app. Use the preconfigured snippet that is already populated with the configuration values from your mobile app.

All Android Agent start-up related properties are part of the AutoStart DSL and must be configured via the autoStart block:

Download
dynatrace {
    configurations {
        sampleConfig {
            autoStart {
                applicationId '<YourApplicationID>'
                agentPath '<YourAgentPathUrl>'
            }
        }
    }
}

The auto-start injection feature starts the Agent in the Application.onCreate method. If your app supports Direct Boot, you have to deactivate the auto-start injection feature.

Deactivate auto-start injection

You can deactivate the auto-start injection feature with the enabled property. You cannot specify the applicationId and the agentPath properties because these values must be used in the manual startup call.

Download
dynatrace {
    configurations {
        sampleConfig {
            autoStart.enabled false
        }
    }
}

Add the startup call manually to the Application.onCreate method. For more information, see the Start Agent section in the Android Agent SDK documentation.

Dynatrace.startup(this, new AppMonConfigurationBuilder("YourApplicationID", "YourAgentPathUrl")
	... // additional configuration
	.buildConfiguration());
Note

Additional configuration changes specified via AppMonConfigurationBuilder override the configuration values defined via the Android Gradle plugin DSL.

Exclude certain classes and methods

Auto-instrumentation instruments all packages by default. If you want to exclude certain classes, you have two options:

Exclude a list of packages, classes, and methods via the packages, classes, and methods properties

Download
dynatrace {
    configurations {
        sampleConfig {
            exclude {
                packages "com.mypackage", "com.another.example"
                classes "com.example.MyClass"
                methods "com.example.ExampleClass.exampleMethod", "com.example.ExampleClass\$InnerClass.anotherMethod"
            }
        }
    }
}

These properties contain some additional features:

  • packages automatically excludes sub-packages
  • classes automatically excludes inner classes
  • methods automatically excludes all methods with the same name (regardless of the method signature)
Note

Escape the $ character for inner classes as shown in the above example.

Use the custom exclude filter

This option allows you to define a finer granular exclusion logic via additional filter rules. In the filter you can define a regex for className, methodName, and methodDescription.

  • For the className property, the fully qualified name is used.
  • A class name matches when the specified expression is found somewhere in the class name
  • A method name matches when the specified expression is found somewhere in the method name
  • A method description matches when the specified expression is found somewhere in the method description
Download
dynatrace {
    configurations {
        sampleConfig {
            exclude {
                // exclude all inner classes
                filter {
                    className "\$"
                }

                // exclude all methods that fulfill this requirements
                filter {
                    // the class is part of the "com.example" package
                    className "^com\\.example\\."
                    // the method name contain the phrase "webrequest" (uppercase notation is ignored for two letters)
                    methodName "[wW]eb[rR]equest"
                    // where the last parameter is a String and where the return value is void
                    methodDescription "Ljava/lang/String;\\)V"
                }
            }
        }
    }
}

Adjust test case instrumentation

The plugin only executes the auto-instrumentation step when the app is built. Therefore, the behavior of local unit tests and instrumented unit tests is different.

Local unit tests

Local unit tests directly use the classes generated by the Java (or Kotlin) compiler and the auto-instrumentation step of the plugin is never executed. Because method calls to Android Agent SDK are placed in the source code, they are also available and executed in your local unit tests. However, the Agent is not started and the method calls are ignored.

Local unit tests with Robolectric

Robolectric allows you to simulate Android in your local unit tests. Like regular unit tests, Robolectric uses the classes generated by the compiler that are not auto-instrumented. But if you have deactivated auto-start injection and started Android Agent manually in the Application class, the agent runs and monitors your Robolectric test cases. In this case, adjust your configuration by either separating development and production monitoring data or using a different build type for unit tests.

Instrumented unit tests

To run instrumented unit tests on a device or emulator, the Android build generates two APK files. First, the APK file of the app you want to test is generated. The plugin is part of this build process and auto-instruments the APK file. The Android build generates a test APK that contains the class for testing the other APK. The plugin is also part of this build process. But it will notice that a test APK is generated and therefore doesn’t auto-instrument these test APKs.

Because the APK is instrumented, every instrumented unit test is monitored. In this case, you should adjust your configuration by either separating development and production monitoring data or using a different build type for unit tests.

Use a different build type for unit tests

For a customized instrumentation behavior for your unit tests, generate a new build type for your unit tests with the plugin.

Download
android {
    buildTypes {
        // build type used for unit tests in the CI
        CI {
            initWith debug
            applicationIdSuffix ".debugTesting"
        }
    }
}

For example, if you want to monitor your debug builds used by the developers and you don't want to monitor the unit test execution in the CI, use the following configuration:

Download
dynatrace {
    configurations {
        developer {
            variantFilter "[dD]ebug"
            autoStart {
                applicationId '<DebugApplicationID>'
                agentPath '<DebugAgentPathUrl>'
            }
        }
        ciTesting {
            // deactivate instrumentation for CI tests
            variantFilter "CI"
            enabled false
        }
        prod {
            variantFilter "[rR]elease"
            autoStart {
                applicationId '<ProductionApplicationID>'
                agentPath '<ProductionAgentPathUrl>'
            }
        }
    }
}

Note: When developers execute the unit tests with the debug variant, unit tests are monitored because the instrumentation is deactivated only for the CI variant.