Free trial

Advanced settings for Android auto-instrumentation

Find out how you can configure the auto-instrumentation properties for Android.

Lifecycle monitoring

Auto-instrumentation instruments all activities listed in the AndroidManifest.xml file that aren't manually instrumented. Use the DTXInstrumentLifecycleMonitoring property to deactivate lifecycle instrumentation.

With lifecycle instrumentation, OneAgent automatically collects the following data and renders it as actions:

  • Application Start Event: Represents the time from Application.onCreate() to Activity.onPostResume() of the first activity displayed. If no activity is opened at the application start, then the application-start event is not recorded correctly.

  • Activity Display: Represents the time from Activity.onCreate(Bundle) to Activity.onPostResume().

  • Activity Redisplay: Represents the time from Activity.onStart() to Activity.onPostResume().

These activities' display/redisplay actions can also contain web requests or crash events.

Crash reporting

Crash reporting is enabled by default. OneAgent 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.

User action monitoring

Auto-instrumentation allows you to automatically detect user actions. Therefore, auto-instrumentation 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 a user action is open, OneAgent adds all triggered events such as web requests and crashes to this user action. However, 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, auto-instrumentation configures a timeframe. In this timeframe, OneAgent 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.

If this timeframe expires and the action contains unfinished web requests, then OneAgent will wait until these web requests are completed. You can also configure the maximum user action duration with the DTXAutoActionMaxDurationMilliseconds property. The property default value is 60,000 ms (one minute) and the valid range is 100 ms - 540,000 ms. If a web request is still not finished after this period, OneAgent will remove the web request from the user action and close the user action with an appropriate end time value. The value for the DTXAutoActionMaxDurationMilliseconds property must be equal or greater than the value of the DTXAutoActionTimeoutMilliseconds property.

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

You can also deactivate user action monitoring with the DTXInstrumentAutoUserAction property.

Note:
Auto-instrumentation only instruments your byte-code. It doesn't instrument listener methods defined in xml files. You must manually instrument these listener methods. Also, auto-instrumentation doesn't instrument controls placed in a WebView.

Web request monitoring

Auto-instrumentation activates web request tagging and timing for your web requests. OneAgent 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:
Auto-instrumentation doesn't support the OkHttp 3 library obfuscation. You must add the following rule to your ProGuard rules file: -keep class okhttp3.** { *; }

The support for the Apache HttpClient library will be dropped in a future version.

If a web request is triggered by a user action, OneAgent will add the web request as child event to the monitored user action.

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. Auto-instrumentation ignores the DTXInstrumentWebRequestTagging property value when the DTXInstrumentWebRequestTiming property is activated.

Note:
Do not manually instrument web requests that are auto-instrumented—this will lead to incorrect user experience data.

Cluster ActiveGate configuration

Including certificates

If your Cluster ActiveGate does not have a certificate that is issued by a trusted intermediate or root CA then you have to include the certificate you are using into a KeyStore file and provide it to the agent by performing a manual startup via the DESKConfigurationBuilder API. You can also use the Network Security Configuration to provide your certificate.

Note that the Network Security Configuration is only available for apps targeting SDK >= 24.

Certificate pinning

To use certificate pinning, please follow the instructions provided by Android at Network Security Configuration - Certificate Pinning.

Other monitoring settings

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 don't have to change these values, because auto-instrumentation uses your new version name and code.

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

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

Set the DTXLogLevel property to the value debug to activate OneAgent and auto-instrumentation debug logs. Auto-instrumentation and the OneAgent log adds additional information in this mode that helps with troubleshooting problems. It's recommended that this property should be removed when building your PlayStore or production application, because the additional logging can slow down the application. Auto-instrumentation 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. OneAgent logs are available through the logcat tool or view.


The following table sums up all the properties you can use to fine-tune your instrumentation.