Android auto setup and instrumentation

Android auto-instrumentation lets anyone instrument Android applications for monitoring using the mobile agent. Instrumentation automatically adds the mobile agent to an application without manually modifying source code. Data collection is the same with an auto-instrumented application as it is with a manually instrumented application.

You can start the auto-instrumentation process the following ways:

  • Call instrument.<cmd_or_sh> apk=<app-name>.apk prop=<prop-name>.properties from the command line.
  • Integrate the auto-instrumentation process into your Gradle build process with the Dynatrace Gradle plugin

Auto-instrumentation from the command line

See the Android requirements before running the auto-instrumentor the first time.

  1. Download the newest mobile agent. The file name is dynatrace-mobile-agents-<version>.zip. Unpack it to a directory of your choice.
  2. Copy the APK-Instr.properties property template file from the <MobileAgentUnzipDir>/Android/auto-instrumentor directory to a directory of your choice, and rename it.
  3. Edit the properties file to customize the auto-instrumentation process. The DTXApplicationID and DTXAgentStartupPath properties are required.
  4. Run the instrument command with the apk and prop parameters, for example, instrument.<cmd_or_sh> apk=<app-name>.apk prop=<prop-name>.properties.
  5. Sign the instrumented APK <pathToYourApk>/<nameOfAPK>/dist/<nameOfAPK>.apk with your debug or Google playstore certificate, or use the <pathToYourApk>/<nameOfAPK>/dist/<nameOfAPK>-final.apk APK, which is signed with the auto-instrumentor debug certificate.
  6. Start AppMon, including the web server (master) agent and your instrumented web or app server.
  7. Install and run your instrumented APK file.

Auto-Instrumentation features

Auto-instrumentation provides visibility into:

Mobile agent start-up

Because the auto-instrumentor inserts the mobile agent start-up into the beginning of the application start procedure, you can't control the start-up parameters with manual instrumentation because the agent ignores multiple start-up calls.

The DTXApplicationID and DTXAgentStartupPath properties are required. They are needed for the Dynatrace.startup() call. For the DTXApplicationID property, specify a unique application ID. For the DTXAgentStartupPath property, specify the address of your instrumented web or application server. For example:

DTXApplicationID=YourUniqueAppId
DTXAgentStartupPath=http://<instrumentedWebOrAppServer>[:portIfNot80]

Specifying an HTTPS address in the DTXAgentStartupPath property lets the agent verify the server certificate and the host name. The agent communication with the instrumented web or application server fails when verification steps can't complete successfully.

If you don't have a root certificate for your instrumented web or application server, you must provide a BKS keystore file, which contains the certificate(s) for SSL communication. Add the keystore file to the raw directory of the APK and specify the BKS file name (without the file extension) in the DTXBKSFileName property. You also must specify the keystore file password in the DTXBKSPassword property. For example:

# for file raw/mykeystore.bks use
DTXBKSFileName=myKeyStore
DTXBKSPassword=myPassword

The keystore password is not secured and can be retrieved by decompiling the application.

Another option is to deactivate the certificate validation with the DTXAllowAnyCert property. Host name verification can't be deactivated.

Lifecycle data

The auto-instrumentor instruments all activities listed in the AndroidManifest.xml file that are not manually instrumented. Use the DTXInstrumentLifecycleMonitoring property to deactivate lifecycle instrumentation. See Collected lifecycle data for more information.

Crash reporting

Crash reporting is enabled by default. The mobile agent captures all unhandled exceptions/errors and sends the crash report immediately to the server. The Android crash report includes the occurrence time and the full stack trace of the exception. The crash report is attached to the user action that has triggered the exception.

Use the DTXCrashReportingEnabled property to disable crash reporting. Then the auto-instrumentor does not insert the method call Dynatrace.enableCrashReporting(boolean sendCrashData) into your applications start procedure. If you deactivate crash reporting, the agent ignores the corresponding value from your user experience configuration.

User action monitoring

Auto-instrumentation allows you to automatically detect user actions. Therefore the auto-instrumentor instruments the following listeners and methods:

  • Android
    • method: android.app.Activity.onOptionsItemSelected
    • android.view.MenuItem$OnMenuItemClickListener
    • android.view.View$OnClickListener
    • android.widget.AdapterView$OnItemClickListener
    • android.widget.AdapterView$OnItemSelectedListener
  • Android Support
    • android.support.v4.view.ViewPager$OnPageChangeListener
    • android.support.v4.widget.SwipeRefreshLayout$OnRefreshListener
  • ActionBarSherlock
    • method: com.actionbarsherlock.app.SherlockActivity.onOptionsItemSelected
    • com.actionbarsherlock.internal.widget.IcsAdapterView$OnItemSelectedListener
    • com.actionbarsherlock.view.MenuItem$OnMenuItemClickListener

While an user action is open, the mobile agent adds all triggered events such as web requests and crashes to this user action. But most user actions are generated in the main thread and their web requests are triggered in a background thread after the user actions are closed. Normally these web requests would not be added to the user action. Therefore the auto-instrumentor configures a time frame. In this time frame the mobile agent adds web requests to the closed user action. You can set this time duration in milliseconds with the DTXAutoActionTimeoutMilliseconds property. The default value for this property is 500 ms and the valid range is 100 ms - 5,000 ms.

You can also configure the maximum duration of the user action with the DTXAutoActionMaxDurationMilliseconds property. The property default value is 60,000 ms (one minute) and the valid range is 100 ms - 540,000 ms. After the first time frame expires, the mobile agent keeps the user action until all outstanding web requests or child actions complete or the user action maximum duration is reached. The mobile agent does not accept web requests during this duration. These web requests are added to other user actions. When the maximum duration is reached, then the mobile agent closes the user action and all outstanding web requests or child actions.

Note

You can only configure one value for the DTXAutoActionTimeoutMilliseconds and DTXAutoActionMaxDurationMilliseconds properties, and these values must fit all user actions on all devices.

By default, the mobile agent discards empty user actions to reduce the amount of data that is sent to the server. If you are interested in these user actions, you can change this behavior with the DTXSendEmptyAutoAction property. You can also deactivate user action monitoring with the DTXInstrumentAutoUserAction property.

Note

The auto-instrumentor only instruments your byte-code. It does not instrument listener methods defined in xml files. You must manually instrument these listener methods.

Also, the auto-instrumentor does not instrument controls placed in a WebView. See How to instrument a hybrid app for more information.

Web request monitoring

The auto-instrumentor activates web request tagging and timing for your web requests. The mobile agent automatically truncates the query from the captured URL and only reports the domain name and path of your web requests.

The following list contains the supported HTTP frameworks:

Note

The auto-instrumentor does not support OkHttp 3 library obfuscation. You must add the following rule to your ProGuard rules file:

-keep class okhttp3.** { \*; }

The mobile agent automatically adds your web requests to the user action that triggered these web requests. For Web requests that can't be assigned to a user action, mobile agent generates a new action and attach the web request to it. The name of this action contains the key word WebRequest and the domain name of the web requests. For example WebRequest(www.domain.com). Use the DTXShowFullWebRequestURL property to replace the name of this wrapping action with the full URL. There is an action name length limit and the web request URL is truncated if it exceeds this limit. The DTXShowFullWebRequestURL property only changes the name of the wrapping action. The web request event is not affected by the property and does not show the full URL.

Deactivate web request tagging and timing with the DTXInstrumentWebRequestTagging and DTXInstrumentWebRequestTiming properties. Because web request tagging is a precondition for web request timing, you can't deactivate tagging without deactivating timing. The auto-instrumentor ignores the DTXInstrumentWebRequestTagging property value when the DTXInstrumentWebRequestTiming property is activated.

Note

When you use auto-instrumentation and activate web request and user action monitoring, is it recommended to renounce manual web request instrumentation for the supported HTTP frameworks. Otherwise, your implementation can have unexpected results.

Additional customization

Auto-instrumentation instruments all packages by default. To skip third party content, use the DTXExcludePackages property to exclude packages, classes, or methods. For example:

DTXExcludePackages=com.xyz.IncludedClass.excludeThisMethod,com.xyz.ExcludedClass

If you only want to instrument your application package, use the DTXIncludePackages property to select the packages and deactivate DTXIncludeAllPackages. You can't include packages using the DTXIncludePackages property, if they are already excluded by the DTXExcludePackages property.

DTXIncludeAllPackages=false
DTXIncludePackages=com.this.pkg,com.that.pkg

To refresh the uninstrumented application with the instrumented application on Google Play, you must change the version number. By default, the auto-instrumentator does not change the version code and name. Use the DTXVersionCode and DTXVersionName properties to change these two values. If you have build a new APK file with a new version name and code, then you do not have to change these values, because the auto-instrumentor uses your new version name and code.

Activate the DTXInstrumentGPSLocation property to monitor the user location. This lets the auto-instrumentor instrument all your location listeners, and appends the captured user position to the sent data. The agent captures only three fractional digits. Your application must request the location permission and implement the location listener. The auto-instrumentor supports the following location listeners:

  • android.location.LocationListener
  • com.google.android.gms.location.LocationListener

Set the DTXLogLevel property to the value debug to activate the agent and auto-instrumentor debug logs. The auto-instrumentor and mobile agent log additional information in this mode that helps support troubleshoot problems. It is recommended to remove this property when building your playstore or production application, because the additional logging can slow down the application. The auto-instrumentor creates a log file AIA_<timestamp>.log in the log directory of your working directory, depending on the terminal where you execute the instrument command. The mobile agent logs are available through the logcat tool or view.

Requirements

  • Supported OS versions (dependence on Google Android SDK system requirements):
    • Windows Vista to 10; other versions may work.
    • Ubuntu 12 and 14, 32 or 64-bits with the right ia32-libs installed; other versions and Linux flavors may work.
    • Mac OSX 10.8 to 10.9; other versions may work.
  • Java SDK 1.8
  • On Linux and OSX make sure that <MobileAgentUnzipDir>/Android/auto-instrumentor/instrument.sh has the execute permission chmod +x instrument.sh.
  • Install ia32-libs on 64-bit Linux.

Limitations

  • The auto-instrumentor has to add the agent code into the primary .dex file. There are some limitations for multi-dex applications.
  • If you obfuscate your application and you use both manual instrumentation and auto-instrumentation, you must exclude the Dynatrace.jar library from obfuscation. See the section ProGuard Settings for more information.
  • The keystore password, if specified, is not secured. It is just as if you coded the password into the application. An attacker can retrieve the password by decompiling the application.
  • Auto-instrumentation only provides limited information for hybrid applications. See How to instrument a hybrid app for more information.
  • Avoid using special characters and spaces in file and path names (such as ( ) [ ] $ % *).  If you are having trouble instrumenting your app, rename your file to use only alphanumeric characters (a-z, A-Z, 0-9) and the dot character (.) and try again.
  • APK protection tools (like DexGuard) are not fully supported.