Android manual setup and instrumentation

Getting Started

Do the following to setup Android apps for instrumentation:

Manual instrumentation features

Manual instrumentation provides visibility into:

Crash reporting

Crash reporting is disabled by default. Call the Dynatrace.enableCrashReporting method to enable or disable crash reporting.

Disabling crash reporting ignores the corresponding value from your user experience configuration.

Enabling crash reporting captures all unhandled exceptions and errors and sends a crash report immediately to the server. The Android crash report includes the occurrence time and the full stack trace of the exception. If the crash occurs while a lifecycle action is active, the mobile agent attaches the crash report to the lifecycle action.

Lifecycle instrumentation

By default, lifecycle data collection is on. You can turn it off in the user experience configuration file.

Complete the following tasks to enable lifecycle data capturing:

You can also use Auto-Instrumentation for Android to automatically perform this instrumentation.

Collected lifecycle data

With lifecycle instrumentation, the mobile agent 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 the first activity does not extend a Dynatrace activity, the application-start event time is not recorded correctly.
  • Activity Display: Represents the time from Activity.onCreate() 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.

User action monitoring

Create user actions with the Dynatrace.enterAction method and close them with the leaveAction method. The resulting action is visible as a mobile user action PurePath in the AppMon client. For example, you can use the enterAction and leaveAction methods to determine how long it takes to pull content from a remote server. You get visibility to the corresponding backend transactions within the action scope. Other event types (reportEvent, reportValue and reportError) can be reported within the context of the action object, thus creating a series of events within an action scope.

The reportError event is different from the reportValue event in that it is specifically identified as an error type of event. The integer value most likely contains an error code. You can also use the Dynatrace.reportError method to create a stand-alone error action.

Note

When the parent action is closed, the mobile agent automatically closes all nested/child actions of the parent action. The mobile agent discards the captured action data (including child actions), when the action is not closed.

Web request monitoring

Web request monitoring is supported for the Apache HttpClient and HttpURLConnection HTTP frameworks. For all other HTTP frameworks, ensure that the Dynatrace mobile tag is placed on the HTTP request.

Web request tagging

Web request tagging lets the AppMon server identify mobile traffic and correlates web request server-side PurePath data to a corresponding mobile user action. To do this, the mobile agent must add an additional HTTP header to your web request. The web server agent analyzes this HTTP header and the AppMon server generates a corresponding web request PurePath. No web request PurePath is generated for web requests to unmonitored servers such as third party servers.

There are two ways to assign a web request to an action.

  • Use the DTXAction.tagRequest methods of a specific action to assign a web request to this action.
  • Use the Dynatrace.tagRequest methods to let the mobile agent assign the web requests to an appropriate user action.

The mobile agent uses the following rule set:

  • If the current thread has an open action, when the request is tagged, then the mobile agent assigns the web request to the open action.
  • If the current thread has no open action, the AppMon server assigns the web request to an action that calls its leaveAction() method in the same thread where the tagging is done. The tagging time must fall between the action enter and leave times.
  • If neither of the preceding cases applies, the web request is not assigned to any action. In this case, the server-side PurePath data is not linked to a mobile user action, but PurePath data can be identified as mobile traffic in the transaction flow.

The tagRequest(java.net.HttpURLConnection) and tagRequest(org.apache.http.HttpRequest) methods generate and add the correct HTTP header to your web request automatically.

DTXAction action = Dynatrace.enterAction("<action_name>");
URL url = new URL("http://myhost.mydomain.com/example");
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
action.tagRequest(connection);

// handle web request

action.leaveAction();
DTXAction action = Dynatrace.enterAction("<action_name>");
HttpGet get = new HttpGet("http://myhost.mydomain.com/example");
action.tagRequest(get);

// handle web request

action.leaveAction();

For the Apache HttpClient library, you can also use the Dynatrace.registerRequestTaggingInterceptor(org.apache.http.impl.client.DefaultHttpClient) method. This method adds the additional HTTP header to all requests executed with the given DefaultHttpClient. The interceptor overwrites any existing tag placed on the request.

For third party libraries, you must use the getRequestTag() general method to generate the correct tag value. You must manually add the needed HTTP header to your web request. Use the Dynatrace.getRequestTagHeader() method to get the header key, as shown below for the OkHttp 3 library.

DTXAction action = Dynatrace.enterAction("<action_name>");
Request request = new Request.Builder()
		.url("http://myhost.mydomain.com/example")
                .addHeader(Dynatrace.getRequestTagHeader(), action.getRequestTag())
                .build();

// handle web request

action.leaveAction();
Note

Web request tagging does not measure network contribution time. The generated web request PurePath only contains the timing values from the server agent. You must use web request timing for full visibility.

Web request timing

Web request timing is an extension of web request tagging. It lets you monitor the web request on the mobile side. It also monitors web requests to unmonitored servers.

You must use web request tagging and create manual timings by using the WebRequestTiming class. The Dynatrace.getWebRequestTiming(java.net.HttpURLConnection) and Dynatrace.getWebRequestTiming(org.apache.http.HttpRequest) methods tag your web request (like the Dynatrace.tagRequest methods) and provide the corresponding WebRequestTiming object. For third party libraries, you must use the general method Dynatrace.getWebRequestTiming(String) and generate the parameter value with the Dynatrace.getRequestTag() method. You must manually add the needed HTTP header to your web request.

Call the startWebRequestTiming method before the web request is sent to the server. Call the stopWebRequestTiming method after receiving and reading the HTTP response. The mobile agent generates a web request action with measured timing values and the AppMon server appends the server PurePath data to this web request action. You can see network timings in the Network Contribution column of the User Actions PurePath dashlet and other dashlets.

Examples

Difference between tagging and timing

When you use web request tagging, the AppMon server generates the corresponding mobile web request PurePath. The timing values are based on the server-side timing values. As shown below, the timing values of the mobile web request don't fit the mobile user action search request. This is because the mobile devices' system clocks differ from the server clock. The mobile agent tries to minimize this offset and provides timing values based on the server time.

Example with web request tagging
Example with web request tagging

When you use web request timing, the mobile agent generates a mobile web request event and sends the data to the AppMon server. The AppMon Server links the PurePath data from the mobile and Server agent. This approach lets you measure the network contribution time and shows the correct time values for mobile nodes in the user action PurePath dashlet. Unfortunately the server node may differ from the mobile nodes because of the system clock difference, as shown below.

Example with web request timing
Example with web request timing

Advanced settings

Most mobile agent-specific settings can be set as parameter for the Dynatrace.startup method. Some advanced settings must be specified by adding a Dynatrace.properties file to the assets folder. The following table shows the available advanced configuration settings.

Key Type Default Description
DTXLogLevel String Debug logs can be activated with the value debug.
DTXAllowFileCookies boolean false Set the value to true to use file cookies.
Note

If you use a combination of manual and auto-instrumentation, the auto-instrumentor overrides the Dynatrace.properties file and your configuration is lost. In this case you must move your configuration settings to the auto-instrumentor properties file. The auto-instrumentor ensures that these properties are handled correctly and are part of the generated Dynatrace.properties file.

The Dynatrace.properties file does not support the other auto-instrumentation properties. You can't use these properties for manual instrumentation, because the corresponding instrumentation is missing.

ProGuard settings

ProGuard is a free Java class file shrinker, optimizer, obfuscator, and preverifier. It detects and removes unused classes, fields, methods, and attributes. It is recommended to exclude all mobile agent classes by adding the following lines to your proguard.pro file:

-keepattributes EnclosingMethod
-keep class com.dynatrace.** { *; }
Note

If you are using a combination of manual and auto-instrumentation, you must exclude all mobile agent classes from obfuscation. This step is necessary, because the auto-instrumentor inserts non-obfuscated code into your application.

If you only use manual instrumentation, you can use ProGuard to obfuscate the Dynatrace.jar library. For hybrid applications, you must exclude the class JsNativeBridgeAPI17 from obfuscation. The class JsNativeBridgeAPI17 is part of the com.dynatrace.android.ext.jsi.jar library .

-keep com.dynatrace.android.ext.jsi.JsNativeBridgeAPI17 { *; }

Limitations and Overhead

  • For Android 4.4 and earlier, the agent can't detect the correct foreground or background application state unless all activity classes are instrumented. You also have to add the GET_TASKS permission.
  • The agent does not contain a specific web request tagging and timing API for third party web request frameworks. You have to use the general API methods (like Dynatrace.getWebRequestTiming(String)).
  • There is limited support for multi-process applications, as each process starts its own agent and has its own session number.
  • Adding the Android mobile agent (whether manually or through auto-instrumentation) to an application increases the size of the application by about 100 KB to 200 KB. The size increase depends on the implementation of your application and how effectively Android can store the mobile agent and the instrumentation code in your .dex files.

The impacts on app performance and mobile data usage are summarized in the general overhead section.