How do I start Android auto-instrumentation from the command line?

With the auto-instrumentation script you can perform auto-instrumentation on an APK file via the command line. The instrumented APK file is signed with a Dynatrace debug certificate, so you can test the instrumented app on the emulator or a developer device. You have to sign the instrumented app with your Google Play certificate before you can upload the instrumented APK to the Google Play store.

Before running auto-instrumentation for the first time, you should check the system requirements for auto-instrumentation.

Run auto-instrumentation from the command line

To run auto-instrumentation from the command line:

Click Applications in the navigation menu.

Select your mobile application.

Click the browse button (...) in the top right corner and select Edit.

Click Instrumentation in the left menu.

Select Google Android.

Select the Command line tab.

Download the latest OneAgent version for Android apps. The file name is dynatrace-mobile-agents-<version>.zip. Unpack it to a directory of your choice. You will find the auto-instrumentation script in the following folder <MobileAgentUnzipDir>/Android/auto-instrumentor.

Create an empty auto-instrumentation property file.

Copy the provided auto-instrumentation property values into your empty auto-instrumentation property file.

Optionally, you can customize auto-instrumentation by setting additional properties. If you have a multidex app, check the auto-instrumentation properties specific for multidex apps.

Optionally, you can enrich auto-instrumentation by adding Mobile OneAgent SDK calls. To do this, add the library Dynatrace.jar from the folder Android/agent to your project. In Android Studio, place the Dynatrace.jar file in the default library folder <project_name>/<module_name>/libs. Your module's build.gradle configuration imports it with the dependency implementation fileTree(dir: 'libs', include: ['*.jar']). Then you are able to use the Mobile OneAgent SDK calls.

Note:
The added Dynatrace.jar library and the auto-instrumentation script must have the same version number.

Run the instrument command with the apk and prop parameters, for example:

Auto-instrumentation generates a working folder (with the name of the APK file) at the location of the provided APK file and stores the result in the dist folder. The path to this folder will be <pathToYourApk>/<nameOfAPK>/dist/.

There are three APK files in this folder:

  • <nameOfAPK>.apk: The instrumented APK file. The signing information of this file is invalid. Therefore it has to be signed before it can be used.
  • <nameOfAPK>-zipaligned.apk: Intermediate file. The instrumented APK file is zipaligned but not signed.
  • <nameOfAPK>-final.apk: This instrumented APK file is signed with a Dynatrace debug certificate. It can be directly installed on emulators and/or developer devices.

To upload your mobile app on Google Play, you have to sign the instrumented APK <pathToYourApk>/<nameOfAPK>/dist/<nameOfAPK>.apk with your Google Play certificate. The auto-instrumentation script does not automatically sign the instrumented APK file with your Google Play certificate. Therefore, you have to do this step manually. First, you have to zipalign the APK file and then you have to use the tool apksigner to sign the APK file with your Google Play certificate.