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 public Security Gateway, you must provide a certificate for SSL communication. This can be done by either providing the server certificate in the Network Security Configuration (for Android Target SDK 24 or later) or by providing a keystore with the certificate included.

If you want to use the Network Security Configuration feature, just add a domain-config section to your network-security-config XML. For example:

<domain-config>
	<domain includeSubdomains="true">your.domain.com</domain>
	<trust-anchors>
		<certificates src="@raw/your_server_certificate" />
	</trust-anchors>
</domain-config>

When your Android target SDK is below 24 or you don't want to use the Network Security Configuration feature, then you have to perform the following steps:

  1. Deactivate the auto-start injection with the property DTXAutoStart:
    DTXAutoStart=false
    
  2. Manually start the agent in the Application.onCreate method.
  3. Provide the KeyStore file via the ConfigurationBuilder API.

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

AppMon 2018 April
AppMon 2018 October

You can also deactivate the auto-start injection feature with the DTXAutoStart property. In this case you don't need to specify the DTXApplicationID and DTXAgentStartupPath properties, because you have to specify these values in the manual startup call. You need add the startup call manually into the Application.onCreate method and load the auto-instrumentation configuration with the AppMonConfigurationBuilder.loadDefaultProperties(Context) method. For more information, see the Advanced settings section.

Dynatrace.startup(this, new AppMonConfigurationBuilder("YourAppId", "http://myhost.mydomain.com")
	.loadDefaultProperties(context)
	...
	.buildConfiguration());

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. Web requests that can't be assigned are sent as standalone web requests.

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

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.
  • You can't auto-instrument apps with minSDK higher or equal to 24, because dex files format change has been introduced. If you don't use the new language features, and downgrade to the Android Gradle plugin 2.3.3, it is still possible to generate an APK file in the old format and use auto-instrumentation. Manual instrumentation is not affected.
  • The Agent does not support Direct Boot mode. You have to manually startup the Agent (see DTXAutoStart property) once the device is unlocked.