Mobile Application Monitoring - Free Edition

Transcription

1 Mobile Application Monitoring - Free Edition Android ADK User Guide November 2013

2 Please direct questions about dynatrace or comments on this document to: APM Customer Support FrontLine Support Login Page: Copyright 2013 Compuware Corporation. All rights reserved. Unpublished rights reserved under the Copyright Laws of the United States. U.S. GOVERNMENT RIGHTS-Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in Compuware Corporation license agreement and as provided in DFARS (a) and (a) (1995), DFARS (c)(1)(ii) (OCT 1988), FAR (a) (1995), FAR , or FAR (ALT III), as applicable. Compuware Corporation. This product contains confidential information and trade secrets of Compuware Corporation. Disclosure is prohibited without the prior express written permission of Compuware Corporation. Use of this product is subject to the terms and conditions of the user's License Agreement with Compuware Corporation. Documentation may only be reproduced by Licensee for internal use. The content of this document may not be altered, modified or changed without the express written consent of Compuware Corporation. Compuware Corporation may change the content specified herein at any time, with or without notice. All current Compuware Corporation product documentation can be found at Compuware, Compuware APM, dynatrace, and other names and logos identifying Compuware products are trademarks or registered trademarks of Compuware Corporation. Adobe Reader is a registered trademark of Adobe Systems Incorporated in the United States and/or other countries. All other company and product names are trademarks or registered trademarks of their respective owners. Local Build: November 5, 2013, 13:38

3 Contents Contents Introduction Documentation Conventions Getting Help Chapter 1 Overview Supported Platforms Best Practices Chapter 2 Getting Started Overview of the Instrumentation Process Required Permissions Installing the CompuwareUEM Eclipse Plug-in Adding the Android ADK to the Project Basic Instrumentation Chapter 3 Instrumentation Details Methods for Instrumentation CompuwareUEM.setMonitorCookie() CompuwareUEM.startup() CompuwareUEM.shutdown() CompuwareUEM.enableCrashReporting() UemAction.enterAction() UemAction.leaveAction() UemAction.reportEvent() UemAction.reportValue() UemAction.reportError() CompuwareUEM.reportError() UemAction.tagRequest() CompuwareUEM.tagRequest() CompuwareUEM.registerRequestTaggingInterceptor() CompuwareUEM.getRequestTagHeader() CompuwareUEM.getRequestTag() CompuwareUEM.flushEvents()

4 Contents CompuwareUEM.uemCaptureStatus() CompuwareUEM.setGpsLocation() CompuwareUEM.registerWebView() Return Code Definitions Instrumenting a Service Application Lifecycle Instrumentation Logging Chapter 4 Collected Data Chapter 5 Viewing Application Data Mobile Application Performance Page Summary Tab Performance Tab Availability Tab Drilling Down to Crash Details Analytics Tab Event Tracking Tab Profile Page Index

5 INTRODUCTION This guide provides information and instructions for using the Mobile Application Monitoring - Free Edition Android ADK to instrument your Android applications to collect performance data directly from your application running on mobile devices. Documentation Conventions The following font conventions are used throughout documentation: This font Bold Citation Documentation Conventions [p. 5] Fixed width Fixed width bold Fixed width italic Menu Item Screen Code block Indicates Terms, commands, and references to names of screen controls and user interface elements. Emphasized text, inline citations, titles of external books or articles. Links to Internet resources and linked references to titles in Compuware documentation. Cited contents of text files, inline examples of code, command line inputs or system outputs. Also file and path names. User input in console commands. Place holders for values of strings, for example as in the command: cd directory_name Menu items. Text screen shots. Blocks of code or fragments of text files. Getting Help When you are logged in to the Mobile Application Performance page, use the links on the left side to display support resources. 5

6 Introduction Getting Started The Getting Started page provides basic instructions for downloading and instrumenting the ADK. Support Center The Support Center page contains links to display the ios and Android versions of the user guide; go to the Compuware YouTube channel to view tutorial videos; access the Compuware APM Community forum for Mobile Application Monitoring - Free Edition; or send to request additional information or help. If no data is displayed for an instrumented application, refer to the troubleshooting suggestions displayed on this page. Mobile App Community Use this link to go directly to the Mobile Application Monitoring - Free Edition forum in the Compuware APM Community. The forum includes an Open Q&A section where you can post questions or share information with other users. To log in, go to If you have forgotten your username or password, click the Forgot your username or password? link to retrieve the information. If you have questions not addressed by the available support resources, send to [email protected]. 6

7 CHAPTER 1 Overview Mobile Application Monitoring - Free Edition is a SaaS solution that monitors mobile performance from the real user perspective. It provides performance statistics, crash reporting, and business analytics for native mobile applications. You can track the numbers of users and application sessions across geographical locations, devices, and networks; review performance by device; analyze the impact of device characteristics such as signal strength, battery charge, and memory; and investigate the causes of crashes and errors. You can upgrade seamlessly from the Free Edition to the Professional Edition. For a comparison of the features in the Free Edition vs. the Professional Edition, log in to the Mobile Application Performance web site at and select the Upgrade link. Supported Platforms The Android ADK is currently supported for Android versions 2.2 and above. Best Practices Privacy Policies for Capturing Mobile End User Data Mobile applications are governed under the respected terms and conditions of such applications, which may include providing end-users with explicit information about the data that is collected and reported from the applications that are running on the end user's mobile device. You and your organization are responsible for complying with all such terms and conditions, as well as any or all applicable laws concerning data collection and end-user privacy that may require notices, consent, or opt-in screens. The Android ADK capabilities include the collection of information such as connection type, available memory, application execution time, and battery strength. All data is collected anonymously and is only used in aggregate form. Such data is only collected to improve the quality of the mobile application and Compuware shall only use aggregated data to determine the effectiveness of the mobile application. 7

8 Chapter 1 Overview Verifying Your Server URL Before instrumenting your application, obtain your account ID and server URL string from the portal. Your Server URL maps the data collected from your mobile application to your account. If an incorrect server URL is used, your data will not be available in the Mobile Application Performance page. Naming the Application Events Name your application events so they are easy to identify in the reporting portal. The application event name can be up to 240 characters. In the Mobile Application Performance page, special characters and blanks in your application name and event names will be replaced by underscores. 8

9 CHAPTER 2 Getting Started This chapter is intended to help mobile application developers get up and running as quickly as possible with the Android ADK. It is assumed that you already have experience developing, building, and deploying Android applications and are familiar with the Eclipse IDE with Android SDK Tools installed. Eclipse IDE version is referenced in this guide. For more information, visit Overview of the Instrumentation Process Instrumenting your mobile application involves the following tasks: 1. Download the Android ADK. The ADK is available through the Getting Started page in the reporting portal. See your activation for details. 2. Install the CompuwareUEM Eclipse plug-in. 3. Include the Android ADK library in your Eclipse build environment. 4. Instrument and test the mobile application. Required Permissions To collect performance data, you must include permissions in the AndroidManifest.xml file. NOTE You can assign these permissions when you add the ADK to the Eclipse project. For more information, see Adding the Android ADK to the Project [p. 11]. To be able to use the Android ADK, the application needs the following permissions: <uses-permission android:name="android.permission.internet"/> This permission is used for communication with the Compuware APM servers. <uses-permission android:name="android.permission.access_network_state"/> 9

10 Chapter 2 Getting Started This permission is used prior to communications with the Compuware APM servers to ensure that there is an available network. <uses-permission android:name="android.permission.access_wifi_state"/> This permission is used for reporting: WiFi connection types. WiFi signal strength. WiFi link speed. The following permissions are optional, depending on the data you want to collect: <uses-permission android:name="android.permission.get_tasks"/> This permission is used only for lifecycle instrumentation. <uses-permission android:name="android.permission.read_phone_state"/> Add this permission if you want to report device signal strength. If the permission is not provided, Signal Strength will be blank in the reporting portal. <uses-permission android:name="android.permission.access_fine_location"/> Add this permission to collect the device's GPS location. For more information, see CompuwareUEM.setGpsLocation() [p. 23]. For more information about the AndroidManifest.xml file and Android permissions, see Installing the CompuwareUEM Eclipse Plug-in The CompuwareUEM Eclipse plug-in provides a context menu to add the Android ADK to eligible Android projects within Eclipse. 1. In Eclipse, add the software repository for 2. In the Available Software window, select the Compuware Mobile App Monitoring Android ADK feature. 10

11 Chapter 2 Getting Started 3. Click Next, accept the terms of the license agreement, and click Finish. 4. Restart Eclipse. After Eclipse is restarted, Toggle Compuware Mobile App Monitoring appears on the context menu when you right-click an asset in Package Explorer. Adding the Android ADK to the Project Before You Begin Required Software Eclipse IDE. The recommended version is Eclipse Android SDK Tools. For more information, refer to CompuwareUEM Eclipse plug-in. For more information, see Installing the CompuwareUEM Eclipse Plug-in [p. 10]. 1. In Package Explorer, right-click the Android project and select Toggle Compuware Mobile App Monitoring from the menu. 2. Select Add Compuware Mobile App Monitoring, then click OK. The Android ADK libraries are added to the project. 3. When a list of Android Permissions appears, copy all of the items in the list. 4. Paste the permissions you just copied into the AndroidManifest.xml file. Paste the permission items into the file right after the <uses-sdk /> section, as shown in the example below. 11

12 Chapter 2 Getting Started 5. Click OK to dismiss the dialog box. Basic Instrumentation Complete the following steps to add monitoring capability to your mobile app. After you complete the basic instrumentation procedure, you can fine-tune the data collection by adding events and by configuring your application to monitor lifecycle events. For more information, see Instrumentation Details [p. 15]. 1. Import the CompuwareUEM class where appropriate. import com.compuware.uem.android.compuwareuem 2. Add the following method call to the oncreate() method of your main activity: CompuwareUEM.startup(this, "My_Android_App", "URL_provided_in_your_activation_ ", false, null) Where My_Android_App is the name of your application and URL_provided_in_your_activation_ is the full URL, which includes your account ID: for example, (abcdef represents your account ID). This URL is provided through the you received when you registered, and in the support page when you are logged in to the Mobile Application Performance page. 3. Add performance monitoring. a. Add the following in the oncreate() method of your main activity. UemAction testaction = CompuwareUEM.enterAction("My_Android_Test_Action") Where testaction is a class member and My_Android_Test_Action is the name of your action. b. Add the following at a later place in your app: testaction.reportevent("my_android_test_action") c. Add the following method in the onresume() method of your main activity. CompuwareUEM.leaveAction() 4. Enable crash reporting. CompuwareUEM.enableCrashReporting(true) 12

13 Chapter 2 Getting Started This method enables the Android ADK to report unhandled exceptions. NOTE Crash reporting must be enabled to provide accurate data for Availability metrics, because availability is calculated based on the number of crashes. For more information, see Availability Tab [p. 34]. 5. Compile and run the application. 13

14 Chapter 2 Getting Started 14

15 CHAPTER 3 Instrumentation Details Methods for Instrumentation Two classes are defined in CompuwareUEM.jar. The CompuwareUEM class is used to manage the ADK operations. The UEMAction class is used to create actions and report against them. This section describes the methods available in the Android ADK for instrumenting your mobile application to collect performance data. For more information, see Return Code Definitions [p. 23]. Some methods include functionality that is only available in the Professional Edition, as noted below. When you include these methods in the instrumentation for the Free Edition, the functionality is automatically available upon upgrading to the Professional Edition. CompuwareUEM.setMonitorCookie() This method can be instrumented in the Free Edition, but data is only reported when you have upgraded to the Professional Edition. Call the method to define a cookie string to be sent along with every HTTP GET/POST method call made by the ADK (when establishing contact with the backend or sending data to it). The use of this method is not typical. If called, this method must be invoked before the startup is called to ensure prompt and successful contact with the backend. It can be invoked again to change the cookie string thereafter. Syntax void CompuwareUEM.setMonitorCookie(String cookiestring) Parameter cookiestring A cookie string such as "MIGRATION_FLAG=3" or "n1=v1; n2=v2". CompuwareUEM.startup() Call this method to initialize the ADK for capturing and reporting data. It is recommended that it be invoked as early as possible in your application startup sequence. A common place for the startup() call is the oncreate() function of the main activity. 15

16 Chapter 3 Instrumentation Details Syntax int CompuwareUEM.startup(final Context context, final String sapplid, final String agentpath, boolean useanycert, KeyStore keystore) Parameters context The Android context. sapplid An application identifier (for example, "HelloWorldApp"). agentpath The path to the placed UEM agent (for example, "abcdef.m.axf8.net"). useanycert Allow any certificate for HTTPS communication. This variable will only be evaluated if you specified the HTTPS transport mechanism in agentpath. keystore The key store holding the certificate(s) for SSL communication. This parameter will only be used if the agentpath specifies HTTPS and useanycert is false. The value of keystore can be null if not used. Return Values CPWR_UemOn CPWR_Error_InvalidParameter CompuwareUEM.shutdown() Use this method when you want to stop collecting data. The method shuts down the ADK gracefully. The ADK also attempts to flush the data for up to 5 seconds. Any remaining data after this period is flushed on the next application start. NOTE Call CompuwareUEM.flushEvents() if all data is to be flushed right away. Syntax void CompuwareUEM.shutdown(); CompuwareUEM.enableCrashReporting() This method enables the Compuware UEM crash handler to report crashes, i.e., uncaught exceptions in your application threads. In the event of an uncaught exception, the UEM crash handler will process the exception for reporting and pass on the exception to the default uncaught exception handler. NOTE A crash is only processed and reported if the ADK is initialized and active (return code CPWR_UemOn), and the sendcrashdata parameter is enabled. If the same exception reoccurs within seven days, the crash data is not reported again; but a crash event is reported referencing the previously reported crash data. Crash reporting must be enabled to collect accurate availability data. 16

17 Chapter 3 Instrumentation Details Syntax void CompuwareUEM.enableCrashReporting(boolean sendcrashdata) Parameter sendcrashdata Assign a value of true to send crash data; or false if you do not want crash data sent. UemAction.enterAction() This method creates an action object for reporting the time elapsed between two user-defined times, a start interval and an end interval, in the application lifecycle. Other event types can be reported within the context of the action object, creating a series of events within an action scope. For example, you can use an enteraction and a leaveaction to determine how long it takes to pull content such as a large image or a large volume of configuration data into your application from a remote server. An enteraction must have a corresponding leaveaction to complete the action. In the Professional Edition, the action results in a mobile action PurePath in Compuware APM. Syntax UemAction CompuwareUEM.enterAction(String actionname) UemAction UemAction.enterAction(String actionname) Using the syntax shown below, enteraction() starts an action that is a child of the specified parentaction. UemAction CompuwareUEM.enterAction(String actionname, UemAction parentaction) UemAction UemAction.enterAction(String actionname, UemAction parentaction) Parameters actionname The name by which you will identify the action event in the collected data. parentaction A parent UemAction object. Return Value UemAction object This method always returns a valid action object. NOTE An action cannot run longer than the length of a session. If multiple occurrences of enteraction() with the same name are encountered before the matching leaveaction(), the interval will be calculated from the last enteraction() to the leaveaction(). UemAction.leaveAction() This method ends the action that begins with the preceding enteraction. All reported events for this action and all values collected between the start and end of an action are part of the action. Place a call to this function at the end of the code that you want to time. This reports the number of milliseconds between the enteraction and leaveaction calls. 17

18 Chapter 3 Instrumentation Details NOTE When an outer/parent action is exited, all nested/child actions are automatically closed. Syntax int UemAction.leaveAction() Return Values CPWR_UemOn CPWR_UemOff CPWR_ActionEnded CPWR_Error_NotInitialized UemAction.reportEvent() This method reports the time that the event occurred, relative to the session start time. It can be used to determine when a user passed through a particular view or activity in your application. The reportevent is a simple way to track user behavior in your application. Configure the reportevent, specifying the name of the item you want to capture. A time stamp is added to the event and this data is sent back to the backend database. Syntax int UemAction.reportEvent(String eventname) Parameter eventname The name by which you will identify the named event in the collected data. Return Values CPWR_UemOn CPWR_UemOff CPWR_Error_InvalidParameter CPWR_ActionEnded CPWR_Error_NotInitialized UemAction.reportValue() This method reports a user-defined integer value at any user-defined time in the application lifecycle. For example, if your application receives a variable amount of data each time it makes a request for data, it may be useful to report the number of pieces of data received each time the request is made. The value can be processed by a measure and thus be charted. Syntax int UemAction.reportValue(String valuename, int value) int UemAction.reportValue(String valuename, double value) int UemAction.reportValue(String valuename, String value) 18

19 Parameters valuename The name by which you will identify the custom value event in the collected data. This field can contain up to 240 characters. value The value itself, of the specified data type. Valid integer values for this event are 0 through Return Values CPWR_UemOn CPWR_UemOff CPWR_Error_InvalidRange CPWR_ActionEnded CPWR_Error_NotInitialized CPWR_Error_InvalidParameter Chapter 3 Instrumentation Details CPWR_Error_NotSupportedInFreeMode The syntax reportvalue(string, double) is only supported in the Professional Edition. UemAction.reportError() This event sends a key=value pair to the Compuware APM server. In the Professional Edition, it results in an error node of the calling mobile action PurePath. Syntax int UemAction.reportError(String errorname, int errorcode) int UemAction.reportError(String errorname, Throwable throwable) Parameters errorname The error name as a character string. errorcode or throwable An integer that represents the error code. If throwable, only tostring() is reported. Return Values CPWR_UemOn CPWR_UemOff CPWR_Error_InvalidParameter CPWR_ActionEnded CPWR_Error_NotInitialized CPWR_ReportErrorOff CPWR_Error_NotSupportedInFreeMode The syntax reporterror(string, Throwable) is only supported in the Professional Edition. CompuwareUEM.reportError() This method of the CompuwareUEM class sends a key=value pair to the Compuware APM server, outside of the context of any action. 19

20 Chapter 3 Instrumentation Details It reports a user-defined integer value or an exception at any user-defined time in the application lifecycle. The report error event is different from the custom (integer) value event in that it is specifically identified as an error type of event. The integer value would most likely contain an error code. In the Professional Edition, it results in an error node not in context of any action. Syntax int CompuwareUEM.reportError(String errorname, int errorcode); int CompuwareUEM.reportError(String errorname, Throwable throwable); Parameters errorname The error name as a character string. errorcode or throwable An integer that represents the error code. If throwable, only tostring() is reported. Return Values CPWR_UemOn CPWR_UemOff CPWR_Error_InvalidParameter CPWR_Error_NotInitialized CPWR_ReportErrorOff UemAction.tagRequest() This method can be instrumented in the Free Edition, but data is only reported when you have upgraded to the Professional Edition. The method sets a request tag (the Compuware APM request header) on a web request, which is evaluated by the Compuware APM server to correlate a web request to the calling action. Syntax int UemAction.tagRequest(HttpRequest request) int UemAction.tagRequest(HttpURLConnection conn) Parameters request The request object. conn The request object. Return Values CPWR_UemOn CPWR_UemOff CPWR_Error_InvalidParameter CPWR_ActionEnded CPWR_Error_NotInitialized 20

21 CompuwareUEM.tagRequest() This method can be instrumented in the Free Edition, but data is only reported when you have upgraded to the Professional Edition. The method sets a request tag (the Compuware APM request header) on a web request, which is evaluated by the Compuware APM server to correlate a web request to an action if possible. Since there is no explicit action, the web request is correlated to an action according to the following rule: 1. If there is an open action in the current thread at the time the request is tagged, the web request is assigned (by the ADK) to the open action. 2. If there is no open action in the current thread, the web request is assigned (by the Compuware APM server) 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. 3. If neither of the preceding cases applies, the web request is not assigned to any action. Syntax int CompuwareUEM.tagRequest(HttpRequest request) int CompuwareUEM.tagRequest(HttpURLConnection conn) Parameters request The request object. conn The request object. Return Values CPWR_UemOn CPWR_UemOff CPWR_Error_NotInitialized Chapter 3 Instrumentation Details CompuwareUEM.registerRequestTaggingInterceptor() This method can be instrumented in the Free Edition, but data is only reported when you have upgraded to the Professional Edition. Call this function to register an interceptor that will automatically set a request tag (the Compuware APM request header) on each web request, which is evaluated by the Compuware APM server to correlate a web request to an active action if possible. The rule described for CompuwareUEM.tagRequest() is applied. Syntax int CompuwareUEM.registerRequestTaggingInterceptor(DefaultHttpClient client) Parameter client The DefaultHttpClient object where the interceptor will be registered. Return Values CPWR_UemOn CPWR_UemOff CPWR_Error_InvalidParameter CPWR_Error_NotInitialized 21

22 Chapter 3 Instrumentation Details CompuwareUEM.getRequestTagHeader() This method can be instrumented in the Free Edition, but data is only reported when you have upgraded to the Professional Edition. This method returns the Compuware APM request tag header name to be used in conjunction with the value returned by getrequesttag(). Syntax String CompuwareUEM.getRequestTagHeader() Return Value "X-dynaTrace" Request tag header key/name. CompuwareUEM.getRequestTag() This method can be instrumented in the Free Edition, but data is only reported when you have upgraded to the Professional Edition. Used with getrequesttagheader(), this method provides a way to tag a web request when you cannot use tagrequest(). Syntax String CompuwareUEM.getRequestTag() Return Value Compuware APM tag string Request tag header value, which is specific to a given logic path. The ADK returns an empty string if the current state is not CPWR_UemOn. Example buttonsearch.setonclicklistener(new OnClickListener() public void onclick(view v) {... UemAction uemaction; try { HttpTransportSE androidhttptransport = new HttpTransportSE(url);... uemaction = CompuwareUEM.enterAction("ActionName"); List<HeaderProperty> list = new ArrayList<HeaderProperty>(); list.add(new HeaderProperty(CompuwareUEM.getRequestTagHeader(), CompuwareUEM.getRequestTag())); }); }... androidhttptransport.call(action, envelope, list); } finally { uemaction.leave(); } CompuwareUEM.flushEvents() Call this function to flush all collected events immediately. To reduce network chatter, the collected events are usually sent in packages where the oldest event has an age of up to 2 minutes by default in the Professional Edition, the maximum age can be configured. Using this function, you can force sending of all collected events regardless of their age. Syntax void CompuwareUEM.flushEvents() 22

23 Chapter 3 Instrumentation Details CompuwareUEM.uemCaptureStatus() Use this method to get the current UEM data capturing state. Syntax int CompuwareUEM.uemCaptureStatus() Return Values CPWR_UemOn CPWR_UemOff CPWR_Error_NotInitialized CompuwareUEM.setGpsLocation() This method saves the specified GPS location for reporting along with the captured data. Syntax int CompuwareUEM.setGpsLocation(Location location); Parameter location The location object that contains the device's current GPS location. Return Value CPWR_UemOn Successful. CompuwareUEM.registerWebView() This method can be instrumented in the Free Edition, but data is only reported when you have upgraded to the Professional Edition. Call this function to register a web view so that Java scripts (intended to be executed in the web view) can be instrumented with the Android ADK. Each web view must be registered separately. A call to this method results in enabling JavaScript execution in the registered web views. Blanket web request tagging using the JavaScript function starttaggingrequests also enables the CookieManager to accept cookies. Syntax boolean CompuwareUEM.registerWebView(WebView webview) Parameter webview The web view to be registered. Return Value boolean TRUE if successfully registered; Otherwise, FALSE (such as when running with Android 2.3.x). Return Code Definitions Entering an action always returns a valid action object, regardless of the state of the Android ADK. When you act on an action object such as UemAction.reportEvent(), one of the following return codes is returned. The reported event is not captured unless the CPWR_UemOn code is returned. 23

24 Chapter 3 Instrumentation Details The action is only valid and processed if the leaveaction() method returns CPWR_UemOn. Code CompuwareUEM.CPWR_UemOn CompuwareUEM.CPWR_UemOff CompuwareUEM.CPWR_Error_NotInitialized CompuwareUEM.CPWR_Error_ActionEnded CompuwareUEM.CPWR_Error_InvalidParameter CompuwareUEM.CPWR_Error_InvalidRange Description Data capturing is on; a method call is successful. Data capturing is off. CompuwareUEM.startup(...) is not called or CompuwareUEM.shutdown() is already called. UemAction.leaveAction() is already called. A bad parameter is passed to the method. A bad integer value is passed to the method. CompuwareUEM.CPWR_Error_NotSupportedInFreeMode The operation is only supported in the Premium Edition. CompuwareUEM.CPWR_ReportErrorOff Errors are not reported, because either error reporting is off or only reports in WiFi while on a mobile connection. Instrumenting a Service Application Instrumenting a service is similar to instrumenting an activity-based application. The basic instrumentation procedures are identical and the available data collection methods remain unchanged. However, an instrumented service cannot collect automatic lifecycle events. NOTE To monitor an application that runs as an Android Service, make sure CompuwareUEM.startup() is called before attempting to capture any events. It is recommended to call it from the oncreate() method in the service, as in the following example: public class MyService extends Service public void oncreate() { CompuwareUEM.startup(this, "MyServiceApp", serverurl, true, null);... // other initialization code, etc... } } When this code has executed, you can use all of the basic methods for instrumentation available in the ADK. For more information, see Methods for Instrumentation [p. 15]. Stopping the ADK If the service has finished execution and you no longer want to collect data from any instrumented classes in your application, you can shut down the ADK by inserting the following lines in the ondestroy() method of the public void ondestroy() {... // other code to clean up and shut down your service CompuwareUEM.shutdown(); } 24

25 Chapter 3 Instrumentation Details IMPORTANT If your application is still running and you still want to collect data from instrumented classes, do not call shutdown when the service is destroyed. The reason for this is that only one instance of the ADK can run at any time. Shutting it down when the service is destroyed will make it unavailable elsewhere in your application unless CompuwareUEM.startup() is called again. Lifecycle Instrumentation Use this procedure to enable lifecycle data instrumentation. With lifecycle instrumentation, the ADK automatically collects the following data and renders them as actions: Application start event Represents the time from Application.onCreate() to Activity.onPostResume() of the first activity displayed. Activity display Represents the time from Activity.onCreate() to Activity.onPostResume(). Activity redisplay Represents the time from Activity.onStart() to Activity.onPostResume(). NOTE It is possible for web requests or crash events to appear within the activity display or redisplay actions. Lifecycle data collection is enabled by default when you perform this procedure. In the Professional Edition, it can be disabled. Add lifecycle data instrumentation to your application by editing the AndroidManifest.xml file. 1. Add GET_TASKS permission. <uses-permission android:name="android.permission.get_tasks"/> 2. Do one of the following: If the application element specifies an application class (that is not android.app.application), open that class and change the import statement from, for example, import android.app.application to import com.compuware.android.app.application. Specifically, add the prefix com.compuware. to the package name. IMPORTANT Your application class constructor must call super() and the oncreate() method must call super.oncreate(). If the application element does not specify an application class, add the following: android:name="com.compuware.android.app.application" 25

26 Chapter 3 Instrumentation Details Alternatively, you could use the Application Manifest Application editor in Eclipse to add com.compuware.android.app.application. 3. Update the application activities. For each activity in the application, change the import statement by prefixing com.compuware. to the package name. For example, change import android.app.activity to import com.compuware.android.app.activity. Other supported activities include AliasActivity, ListActivity, ExpandableListActivity, and LauncherActivity. NOTE For com.google.android.maps.mapactivity, change the package name to com.compuware.android.ext.maps.mapactivity. Sherlock ActionBar activities are also supported. For example, change com.actionbarsherlock.app.sherlockactivity to com.compuware.android.ext.sherlock.sherlockactivity. IMPORTANT The root or main activity should extend a CompuwareUEM activity. The Application Start event starts when the application is created (Application.onCreate()) and ends when the first activity is displayed (Activity.onPostResume()). If the first activity does not extend a CompuwareUEM activity, the Application Start event time will be incorrectly recorded. The GET_TASKS permission is used to automatically detect application lifecycle transitions from foreground to background. This method provides the most reliable detection of application state changes if lifecycle monitoring is enabled. It does not collect, store, or transmit which applications are running on a user's device. The Android ADK can only reliably determine the foreground/background transition if all activities extend CompuwareUEM activities. Logging Logging is off by default for the Android ADK. If you need the ADK log, you can change the logging settings at any time. Enable logging by adding this method before the startup call: SharedPreferences sp = PreferenceManager.getDefaultSharedPreferences(this); Editor ed = sp.edit(); ed.putstring("cpwr_diagmode", "1"); ed.commit(); 26

27 CHAPTER 4 Collected Data This table describes the metrics and other data collected by the Mobile Application ADK. Metric Action name Affected users Application name Application version Availability Average response time Battery level Carrier network Carrier usage Crash description Crash occurrence time Crashes Description The name you chose for the action when instrumenting your application. The number of users affected by the crash type or error type. The mobile application name. The version of the application installed on the mobile device. The percentage of time the application successfully started and ran, measured by the following formula: availability % = (sessions crashes) / sessions The average response time (duration) of all application starts and instrumented actions during the selected time period. The battery strength as a percentage of the full charge, reported as a decimal number 0.00 through 1.0, where 1.0 = 100% charged. If the application is running on a device simulator, the battery strength will be zero. The network through which the device is connected to the cellular network or the Internet. The percentage of users connected through each detected carrier. The message that describes the crash. The description is retrieved from the signal or exception name produced by the operating system. The date and time when the crash occurred. In the User Session Log in the Mobile Application Performance page, this metric is labeled Crash Occurred At. The number of crashes that occurred during the selected time period. 27

28 Chapter 4 Collected Data Metric Data value Device Duration Error message Error number Errors Event [or Event name] Event start time Event type Events in sequence Maximum response time Memory usage Minimum response time Mobile platform Network protocol usage Number of applications running Occurrences Report events Report values Sequence number Session duration [or Session length] Sessions Signal strength Description The data returned by the selected report value event. The model and version of the mobile device. The lifecycle duration of an action, displayed as mm:ss:ssss. Events that are not actions have no duration. The description of the error as specified in the report error event. The error message number as specified in the report error event. The number of errors that occurred during the selected time period. The name of the lifecycle event, specified when the application was instrumented. The date and time when an action began. For lifecycle events that are not actions, the date and time the event occurred. The event type designation, and the data type (e.g. String) if applicable. The number of lifecycle events that were completed during the session in which the selected crash occurred. The longest response time within the selected time period. Percentage of total available memory. The shortest response time within the selected time period. The device platform: ios or Android. If the application is running on a device simulator, the operating system is listed. The percentage of users connected via each detected protocol. The number of applications that were active when the crash occurred. The number of times an incident (action, event, or crash type, depending on the reporting context) occurred. The number of report events ( reportevent()) that occurred during the selected time period. The number of report value events (reportvalue()) that occurred during the selected time period. A number assigned to an event in the Session Breakdown Log to identify the event and indicate the order in which events were completed preceding a crash. The amount of time a session lasted. Total number of sessions active during the selected time period. Signal strength measured in dbm. 28

29 Chapter 4 Collected Data Metric Stack trace Start time [or Session start time] Unique users User events User ID Users Users by platform Users by region Description The first 10 lines of the selected session's stack trace. The date and time when the session began. The total number of unique users during the selected time period. A user that has more than one session is only counted once. The total number of report events and report value events executed during the selected time period. The user ID assigned by the application to associate events with that specific user. The number of users that accessed the selected event. The percentage users using devices with each detected platform. The percentage of users in each detected geographic region. 29

30 Chapter 4 Collected Data 30

31 CHAPTER 5 Viewing Application Data View the performance data collected from your users' devices in the Mobile Application Performance page. Before You Begin It is assumed that you have already activated your new account. If you have not yet done so, refer to the Account Activation you received after signing up for your account. NOTE If you have instrumented the application and tested it but no data appears in the Mobile Application Performance page, verify that you used the correct Server URL in the application, and m.axf8.net is specified in the Server URL. If the Server URL is not specified or is incorrect, your data will not appear in the Mobile Application Performance page. It may be that no data appears in the page because no data was generated during the selected time frame. For more information about issues that prevent data from being displayed, include CPWRLog.h in your application and turn on logging. You will be able to see if there are any error messages being logged by the Mobile App ADK code. 1. Log in at The Mobile Application Performance page appears. 2. Use the lists at the top of the window to select the data to display. Application Select the instrumented application for which you want to view the data. Mobile Platform Select whether to view data from All Platforms (the default), Android devices, or ios devices. Time Period Select whether to view data from Last 7 days (the default), Yesterday, Today, or Last 24 hours. 31

32 Chapter 5 Viewing Application Data The charts display data per day if you select Last 7 days, or data per hour for the other Time Period options. 3. Select a tab to view detailed data for the selected category. The Summary tab is selected by default. It displays charts for Performance, Availability, Analytics, and Event Tracking. For more detail about each data category, select the tab for that category. For more information, see Mobile Application Performance Page [p. 32]. At the top of the page are links to support information and additional resources. For more information, see Getting Help [p. 5]. For information about the enhanced features that are available in the Professional Edition, click the Why Go Premium? link. Mobile Application Performance Page The Mobile Application Performance page displays the data collected from instrumented mobile applications. NOTE The first time your instrumented application is started, there is a delay while the application information is propagated to the database. Therefore, the first few minutes of data collected after instrumentation will not be available. After this one-time delay, all collected data will be displayed in the Mobile Application Performance page. Data Filters Use the lists at the top of the page to filter the data: Application Select the instrumented application for which you want to view the data. Mobile Platform Select whether to view data from All Platforms (the default), Android devices, or ios devices. Time Period Select whether to view data from Last 7 days (the default), Yesterday, Today, or Last 24 hours. The charts display data per day if you select Last 7 days, or data per hour for the other Time Period options. Charts Hover over a bar graph or a data point to display the measurement at the selected time. Hover over the measurement displayed to the left of a chart to see a tooltip that explains the measurement. Click a label in the chart legend to remove the data from the graph to focus on data of interest. For example, click Min under the Performance chart to remove the line for the minimum response time. Click the label again to restore the data to the graph. 32

33 Chapter 5 Viewing Application Data Tables You can select columns to display in the tables: Click the list icon at the right side of the table header, then click a column name to hide or display it. Displayed columns have a circle next to the name. You can sort a table column by clicking the column head. You may have to click more than once to sort in the desired order. The columns included in the tables vary depending on the option selected for the Mobile Platform filter. See the table descriptions below for details. Summary Tab The Summary tab is displayed by default. It provides an overview of performance, availability, analytics, and event tracking for the selected application. The charts on this tab are also displayed on the Performance, Availability, Analytics, and Event Tracking tabs, with additional details for each data category. For details, see below. Performance Tab Chart The Performance chart displays line graphs for maximum, average, and minimum response times over time of the Action events and Application Start events. For more information, see Methods for Instrumentation [p. 15]. NOTE The line graph for the maximum values will peak at 2.5 times the highest average, even if the actual maximum value is greater than that. The tooltips for the data points will show the actual maximum value. The average performance displayed to the left of the chart is color coded to indicate performance quality: Green Average response time 3 seconds or less Yellow Average response time 3 5 seconds Red Average response time longer than 5 seconds Table Below the chart, the Action Performance Details table lists information for each action. 33

34 Chapter 5 Viewing Application Data When you select All Platforms in the Mobile Platforms list, the following columns are displayed: Action Name The name you chose for the action when instrumenting your application. All Platforms The average response time in seconds for all devices on all platforms. ios The average response time in seconds for ios devices. Android The average response time in seconds for Android devices. Occurrences The number of times the action occurred. When you select Android or ios in the Mobile Platforms list, the following columns display data from devices running the selected platform: Action Name The name you chose for the action when instrumenting your application. Average The average response time in seconds. Maximum The maximum response time in seconds. Minimum The minimum response time in seconds. Occurrences The number of times the action occurred. The bars next to the values in each column provide a visual indication of the relative values, for example, which actions have the highest or lowest values. The following figure shows the table with All Platforms selected. Availability Tab NOTE To display accurate Availability data, you must have crash reporting enabled. Chart The Availability chart shows the average availability, the number of errors, and the number of crashes for the selected time period. Availability is calculated as a percentage of the total sessions, using the following formula: (sessions crashes) / sessions The availability percentage displayed to the left of the chart is color coded to indicate performance quality: Green Availability 95% or better Yellow Availability 90% to 95% Red Availability less than 90% 34

35 Chapter 5 Viewing Application Data The chart contains: An Availability bar graph for each time interval when data was collected. An Errors line graph with data points for each time interval when errors occurred. Crashes data points for each time interval when crashes occurred. Details Tabs Below the chart, two tabs provide details for crashes and errors: Crash Details The Crash Details tab lists summary information for each crash type. You can drill down from a crash description to display more detailed information. For more information, see Drilling Down to Crash Details [p. 36]. When you select All Platforms in the Mobile Platforms list, the following columns are displayed: Crash Description The message that describes the crash. The description is retrieved from the signal or exception name produced by the operating system. Android The number of sessions during which the crash type occurred on Android devices. ios The number of sessions during which the crash type occurred on ios devices. Affected Users The number of users affected by the crash type or error type. When you select Android or ios in the Mobile Platforms list, the following columns display data from devices running the selected platform: Crash Description The message that describes the crash. The description is retrieved from the signal or exception name produced by the operating system. Occurrences The number of times the crash type occurred. Affected Users The number of users affected by the crash type or error type. The following figure shows the table with All Platforms selected. 35

36 Chapter 5 Viewing Application Data Error Details The Error Details tab lists information for each error type. When you select All Platforms in the Mobile Platforms list, the following columns are displayed: Error Message The description of the error as specified in the report error event. Error Number The error message number as specified in the report error event. All Platforms, Android, and ios The number of times the crash type occurred on all platforms, on Android devices, and on ios devices. Affected Users The number of users affected by the crash type. When you select Android or ios in the Mobile Platforms list, the following columns display data from devices running the selected platform: Error Message The description of the error as specified in the report error event. Error Number The error message number as specified in the report error event. Occurrences The number of times the crash type occurred. Affected Users The number of users affected by the crash type. The following figure shows the table with All Platforms selected. Drilling Down to Crash Details Drill down from the Crash Details table in the Availability tab to review details of crashes, including stack traces. Crash: Session Logs Click an item in the Crash Description column to drill down to information about the user sessions in which the selected crash occurred. 36

37 Chapter 5 Viewing Application Data The crash description, Application name, and Crash Type are listed at the top of the window, which also contains the following information: User Session Log The User Session Log table contains the following columns: User ID The user ID assigned by the application to associate events with that specific user. A user ID may be listed more than once if that user had multiple sessions during which the crash occurred. Session Start Time The date and time when the session began. Crash Occurred At The date and time when the crash occurred. Stack Trace Click the icon to display the Stack Trace tab in a popup window, as described below, for the selected crash occurrence. Events in Sequence The number of lifecycle events that were completed during the session in which the selected crash occurred. Event Sequence Selecting a row in the User Session Log displays a thumbnail of the event sequence. The thumbnail lists the last 10 events that were completed, with the crash name at the bottom of the list. The right side of the thumbnail is a waterfall chart of the event timeline. To hide all events that are not actions, select Show Actions Only below the thumbnail. Click the More Details link below the thumbnail to display the Event Sequence tab, which provides additional information as described below. To return to the Availability tab, click Availability in the top left corner. Stack Trace Tab The Stack Trace tab displays identifying details for the selected session, and the first 10 lines of the session's stack trace. Session Details The session details section provides the following information: Crash The crash description. User ID The user ID assigned by the application to associate events with that specific user. Session Start Time The date and time when the session began. Crash Occurred At The date and time when the crash occurred. Click Device Information to display the following details: Mobile Platform The device platform: ios or Android. If the application is running on a device simulator, the operating system is listed. Device The model and version of the mobile device. Battery Level The battery strength as a percentage of the full charge, reported as a decimal number 0.00 through 1.0, where 1.0 = 100% charged. If the application is running on a device simulator, the battery strength will be zero. 37

38 Chapter 5 Viewing Application Data Memory Usage Percentage of total available memory. Signal Strength Signal strength measured in dbm. Signal strength is only available from Android devices. If the application is running on a device simulator, no signal strength will be listed. Number of Apps Running The number of applications that were active when the crash occurred. Carrier Network The network through which the device is connected to the cellular network or the Internet. Stack Trace The application name and version, and the crash type, are displayed above the lines from the stack trace. Use the Previous and Next links in the top right corner to display information for other sessions without returning to the User Session Log table. To close the window, click the close icon ( X ) in the top right corner. Event Sequence Tab The Event Sequence tab displays the crash description, user ID, and session start time for the selected session. It contains a table that provides the following information for each event: The sequence number. The event name and event type. A bar in the Timeline waterfall chart that graphically depicts the relative start time and duration. The start date and time for the event. The duration of the event. A horizontal line indicating no available data is displayed for events that have no time duration. The final row in the table lists the crash description. The Timeline and Duration columns for the crash display solid red lines. The Start Time column lists the date and time when the crash occurred. To hide all events that are not actions, select Show Actions Only below the table. Use the Previous and Next links in the top right corner to display information for other sessions without returning to the User Session Log table. To close the window, click the close icon ( X ) in the top right corner. Analytics Tab Chart The Analytics chart displays: A Sessions bar graph with data for each time interval when data was collected. A Users line graph with data points for each time interval when data was collected. 38

39 Chapter 5 Viewing Application Data The total number of users and the total number of sessions for the selected time period are displayed to the left of the chart. NOTE A user or session may be represented in multiple intervals. Adding all the intervals together may give a different number than the total, which is the unique users or sessions over the selected time period. A user that has more than one session is only counted once. A session starts when the application is first launched or is activated, and ends when the application is stopped or is inactive for 5 minutes. Each user may have more than one session. Details Tabs The tabs below the chart provide additional detail about users and sessions: Demographics The pie charts provide demographic information about the application's users. Users by Platform The percentage users using devices with each detected platform. Users by Region The percentage of users in each detected geographic region. Network Protocol Usage The percentage of users connected via each detected protocol. Carrier Usage The percentage of users connected through each detected carrier. Hover over a section of a pie chart to see a tooltip that displays the percentage and the actual number of users (or occurrences of a protocol or carrier) that it represents. NOTE If any names in the chart legends are truncated, the tooltip will display the full name. 39

40 Chapter 5 Viewing Application Data Session Length Distribution The Session Length Distribution tab contains a bar graph that enables you to see the typical session length for your application. The x-axis lists session durations ranging from 0 3 seconds through 10+ minutes. The y-axis measures the number of sessions for each duration. For example, you may see that most sessions lasted 3 5 minutes, which is what you would expect for application use. If, however, the graph shows an unexpectedly large number of sessions that lasted only 4 10 seconds, this may indicate that an error occurs within 10 seconds of starting the application. Event Tracking Tab Chart The Event Tracking chart displays bar graphs that depict the number of report value events (reportvalue()) and report events (reportevent()) that occurred at each interval during the selected time period. For more information, see Methods for Instrumentation [p. 15]. To the left of the chart, you can see the total number of events and the number of each type of event for the selected time period. Table The Event Tracking Details table provides information about the events. When you select All Platforms in the Mobile Platforms list, the following columns are displayed: Event The name of the lifecycle event, specified when the application was instrumented. Event Type The event type designation, and the data type (e.g. String) if applicable. Data Value The data returned by the selected report value event. 40

41 Chapter 5 Viewing Application Data All Platforms The number of times this event occurred on both Android and ios devices. Android The number of times this event occurred on Android devices. ios The number of times this event occurred on ios devices Users The number of users that accessed the selected event. When you select Android or ios in the Mobile Platforms list, the following columns display data from devices running the selected platform: Event The name of the lifecycle event, specified when the application was instrumented. Event Type The event type designation, and the data type (e.g. String) if applicable. Data Value The data returned by the selected report value event. Occurrences The number of times this event occurred on devices with the selected platform. Users The number of users that accessed the selected event. The bars next to the values in each column provide a visual indication of the relative values, for example, which events have occurred most often or least often. The following figure shows the table with All Platforms selected. Profile Page In the My Profile page, you can review or update your personal information and select whether to receive related to Compuware products. To display this page, click the My Profile link at the top right of the Mobile Application Performance or Support page. You cannot change your username, account name, or access level. You can update your name and address, change your password, and select different challenge questions for login security. At the bottom of the page, you can select whether to receive s from Compuware to stay informed about technical information, product upgrades and releases, corporate news, and benchmark information. All options are selected by default. If you do not want to receive any category of , clear the check box for that category. After you change any of the information in this page, click Update at the bottom of the page to save the changes. 41

42 Chapter 5 Viewing Application Data 42

43 Index Index A adding Android ADK to Eclipse project 11 AndroidManifest.xml 9 API 15 Availability tab 36 drilldown 36 B best practices 7 C carrier data 38 collected metrics 27 Compuware APM Community 5 CompuwareUEM Eclipse plug-in 10 CompuwareUEM.registerWebView method 23 CompuwareUEM.setMonitorCookie method 15 crash reporting 36 viewing data 36 D data collected 27 E Eclipse plug-in 10 Eclipse project 11 adding Android ADK 11 options 41 enablecrashreporting method 16 enteraction method 17 F flushevents method 22 G getrequesttag method 22 getrequesttagheader method 22 H help 5 I instrumentation 7, 9, 12, 15, See also methods basic 12 best practices 7 lifecycle events 25 overview 9 service application 24 See also methods L leaveaction method 17 lifecycle events 25 logging 26 M methods CompuwareUEM.registerWebView 23 CompuwareUEM.setMonitorCookie 15 enablecrashreporting 16 enteraction 17 flushevents 22 getrequesttag 22 43

44 Index methods (continued) getrequesttagheader 22 leaveaction 17 registerrequesttagginginterceptor 21 reporterror 19 CompuwareUEM class 19 UemAction class 19 reportevent 18 reportvalue 18 setgpslocation 23 shutdown 16 startup 15 tagrequest CompuwareUEM class 21 UemAction class 20 uemcapturestatus 23 Mobile Application Performance page 31 34, 38, 40 Analytics tab 38 Availability tab 34 Event Tracking tab 40 Performance tab 33 Summary tab 33 My Profile page 41 N network data 38 O operating systems 7 P password 41 permissions required 9 privacy policy 7 R registerrequesttagginginterceptor method 21 reporterror method 19 CompuwareUEM class 19 UemAction class 19 reportevent method 18 reportvalue method 18 return codes 23 S service application 24 setgpslocation method 23 shutdown method 16 startup method 15 support 5 T tagrequest method CompuwareUEM class 21 UemAction class 20 U uemcapturestatus method 23 updating personal information 41 user demographics 38 V viewing data 31 34, 38, 40 44