Foglight Application Performance Monitoring SaaS Edition 6.1.0. Mobile App Developer Guide for ios Platforms

Foglight Application Performance Monitoring SaaS Edition 6.1.0 Mobile App Developer Guide for ios Platforms

2014 Dell Inc. ALL RIGHTS RESERVED. This guide contains proprietary information protected by copyright. The software described in this guide is furnished under a software license or nondisclosure agreement. This software may be used or copied only in accordance with the terms of the applicable agreement. No part of this guide may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording for any purpose other than the purchaser s personal use without the written permission of Dell Inc. The information in this document is provided in connection with Dell products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Dell products. EXCEPT AS SET FORTH IN THE TERMS AND CONDITIONS AS SPECIFIED IN THE LICENSE AGREEMENT FOR THIS PRODUCT, DELL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL DELL BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, BUSINESS INTERRUPTION OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF DELL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Dell makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and product descriptions at any time without notice. Dell does not make any commitment to update the information contained in this document. If you have any questions regarding your potential use of this material, contact: Dell Inc. Attn: LEGAL Dept 5 Polaris Way Aliso Viejo, CA 92656 Refer to our web site (software.dell.com) for regional and international office information. Patents This product is protected by U.S. Patents #: 7,979,245 and 8,175,862. Additional Patents Pending. For more information, go to http://software.dell.com/legal/patents.aspx. Trademarks Dell, the Dell logo, and Foglight, IntelliProfile, PerformaSure, and Tag and Follow are trademarks of Dell Inc. "Apache HTTP Server", Apache, "Apache Tomcat" and "Tomcat" are trademarks of the Apache Software Foundation. Google is a registered trademark of Google Inc. Chrome, Android, and Nexus are trademarks of Google Inc. Red Hat, JBoss, the JBoss logo, and Red Hat Enterprise Linux are registered trademarks of Red Hat, Inc. in the U.S. and other countries. CentOS is a trademark of Red Hat, Inc. in the U.S. and other countries. Microsoft,.NET, Active Directory, Internet Explorer, Hyper-V, SharePoint, SQL Server, Windows, Windows Vista and Windows Server are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. AIX, IBM, and WebSphere are trademarks of International Business Machines Corporation, registered in many jurisdictions worldwide. Sun, Oracle, Java, Oracle Solaris, and WebLogic are trademarks or registered trademarks of Oracle and/or its affiliates in the United States and other countries. SPARC is a registered trademark of SPARC International, Inc. in the United States and other countries. Products bearing the SPARC trademarks are based on an architecture developed by Oracle Corporation. OpenLDAP is a registered trademark of the OpenLDAP Foundation. HP is a registered trademark that belongs to Hewlett-Packard Development Company, L.P. Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both. MySQL is a registered trademark of MySQL AB in the United States, the European Union and other countries. Novell and edirectory are registered trademarks of Novell, Inc., in the United States and other countries. VMware, ESX, ESXi, vsphere, vcenter, vmotion, and vcloud Director are registered trademarks or trademarks of VMware, Inc. in the United States and/or other jurisdictions. Sybase is a registered trademark of Sybase, Inc. The X Window System and UNIX are registered trademarks of The Open Group. Mozilla and Firefox are registered trademarks of the Mozilla Foundation. "Eclipse", "Eclipse Foundation Member", "EclipseCon", "Eclipse Summit", "Built on Eclipse", "Eclipse Ready" "Eclipse Incubation", and Eclipse Proposals" are trademarks of Eclipse Foundation, Inc. IOS is a registered trademark or trademark of Cisco Systems, Inc. and/or its affiliates in the United States and certain other countries. Apple, ipad, iphone, Xcode, Mac OS, and Safari are trademarks of Apple Inc., registered in the U.S. and other countries. Ubuntu is a registered trademark of Canonical Ltd. Symantec and Veritas are trademarks or registered trademarks of Symantec Corporation or its affiliates in the U.S. and other countries. YAST is a registered trademark of SUSE LLC in the United States and other countries. Citrix and XenDesktop are trademarks of Citrix Systems, Inc. and/or one or more of its subsidiaries, and may be registered in the United States Patent and Trademark Office and in other countries. AlertSite and DéjàClick are either trademarks or registered trademarks of Boca Internet Technologies, Inc. Samsung, Galaxy S, and Galaxy Note are registered trademarks of Samsung Electronics America, Inc. and/or its related entities. MOTOROLA is a registered trademarks of Motorola Trademark Holdings, LLC. The Trademark BlackBerry Bold is owned by Research In Motion Limited and is registered in the United States and may be pending or registered in other countries. Dell is not endorsed, sponsored, affiliated with or otherwise authorized by Research In Motion Limited. Legend CAUTION: A CAUTION icon indicates potential damage to hardware or loss of data if instructions are not followed. WARNING: A WARNING icon indicates a potential for property damage, personal injury, or death. IMPORTANT NOTE, NOTE, TIP, MOBILE, or VIDEO: An information icon indicates supporting information. Dell Foglight Application Performance Monitoring SaaS Edition Updated - October 2014 Software Version - 6.1.0

Contents Monitor mobile applications........................................ 4 Audience and assumptions.......................................... 4 Overview of Foglight APM SaaS SDKs.................................... 4 What Foglight APM SaaS SDK monitors................................ 4 How captured data is sent to Foglight APM SaaS......................... 5 Mobile app performance: One part of a bigger picture..................... 5 Get started with ios apps.......................................... 6 Get started with the Foglight APM SaaS SDK for ios.......................... 6 Supported HTTP components......................................... 8 Supported versions............................................... 8 Advanced configuration............................................ 8 Sample instrumented ios app........................................ 8 Recording app screens............................................. 9 Recording handled exceptions........................................10 Tracking crashes.................................................10 Hit merging....................................................10 Contacting Dell..................................................11 Technical support resources.........................................11 3

1 Monitor mobile applications When you want to monitor the performance of mobile applications (hereafter called apps) that implement a platform-specific user interface, you use a Dell Foglight Application Performance Monitoring SaaS Edition SDK that extends the platform s software development kit (SDK). The Foglight APM SaaS SDK enables you to capture the details and timing data required to generate performance data for your app. Performance data provides insight into how an end user interacts with your app and the performance of the app from the user s perspective. Foglight APM SaaS analyzes this data and correlates it with other known performance data, such as how long it took an application server to respond to HTTP requests from the app, to help you identify, quantify, and resolve performance issues. This guide introduces the Foglight APM SaaS SDKs, describes how to install an SDK, and provides examples of how to initialize the library and insert method calls within your code. For detailed information about the methods themselves, see the Foglight APM SaaS SDK Reference documentation for your platform. This section provides details about the following topics: Audience and assumptions Overview of Foglight APM SaaS SDKs Audience and assumptions This guide is intended for developers with working knowledge of the software development kit (SDK) and the development tools for their chosen mobile app development environment. The instructions assume that you have an existing app development environment where you can add the Foglight APM SaaS library and modify your code to insert API calls to the library. Overview of Foglight APM SaaS SDKs Foglight APM SaaS offers SDKs for several app development platforms. The SDK packages contain the Foglight APM SaaS library for the selected platform and are available on the foglight.com portal. The functionality provided by the API methods/functions is similar across all platforms, although the library itself differs to suit the SDK. The process by which an API sends captured data back to Foglight APM SaaS for correlation with other performance data is the same. For more details, refer to these topics: What Foglight APM SaaS SDK monitors How captured data is sent to Foglight APM SaaS Mobile app performance: One part of a bigger picture What Foglight APM SaaS SDK monitors The Foglight APM SaaS SDK for ios provides real-time monitoring of your mobile apps on ios devices. With this SDK you can track and analyze the following characteristics of your mobile app: Network activity performance and errors 4

Flow of user activity from screen to screen App crashes and exceptions Device and network information The SDK uses default configuration settings to control various aspects of the SDK. You can modify these settings as needed. For more information about instrumenting your code and what data is captured, see Get started with ios apps. NOTE: You can capture performance data only for the types of data that your app has permission to collect. For example, an app requires the permission of the end user to collect user location. How captured data is sent to Foglight APM SaaS The Foglight APM SaaS library captures data as users interact with the app. Data is accumulated in memory and periodically transmitted to foglight.com in encrypted and compressed HTTP messages. This communication process is designed to optimize data usage and minimize battery consumption on the device. Figure 1. Foglight APM SaaS monitoring an app Foglight APM SaaS analyzes the data, correlates it with data from other sources, and makes data available to users in five-minute intervals. Mobile app performance: One part of a bigger picture When the captured performance data is sent back to Foglight APM SaaS, the data is analyzed and automatically correlated with any related performance data captured through the instrumentation of browsers, Java code, and.net code. For example, consider an app that appears to spend time waiting for content. If an in-house application server is responsible for serving content to the app, Foglight APM SaaS automatically correlates the mobile app performance data with the application server performance data. You can now see where the backend server spent time servicing mobile app requests. 5

2 Get started with ios apps This section describes how to get started with the Foglight APM SaaS SDK for ios and provides code samples for commonly-used API methods: Get started with the Foglight APM SaaS SDK for ios Supported HTTP components Supported versions Advanced configuration Sample instrumented ios app The following topics provide details about a few important areas of ios mobile app monitoring: Recording app screens Recording handled exceptions Tracking crashes Hit merging For information about the API methods themselves (that is, all objects and methods included in the FoglightAPM and FoglightAPMConfig classes), see the Foglight APM SaaS SDK for ios Class Reference available on the foglight.com portal. Get started with the Foglight APM SaaS SDK for ios The Foglight APM SaaS SDK for ios is an ios framework that you add to your Xcode project as a dependency. It contains the FoglightAPM class that provides automatic monitoring functions for your app. The class also supports methods that you can use to instrument your app in order to utilize additional features of the SDK. The following procedure walks you through adding the framework, importing the library into your code, and adding top-level calls to the library. At the end of this procedure, if you run your app, the API automatically begins monitoring HTTP requests and responses, as specified in Supported HTTP components. To install the Foglight APM SaaS SDK for ios in an ios app: 1 Download. Download the Foglight APM SaaS SDK for ios package (ios-sdk-x_x_x.zip) from the foglight.com portal and unzip it to a local directory. The zip contains two folders, with the following files: ios 7.1 ios 8.0 FoglightAPM.framework a folder containing the Foglight APM framework for ios 7 html a folder containing the class reference documentation in HTML format README.html a brief description of the SDK with a link to the online documentation FoglightAPM.framework a folder containing the Foglight APM framework for ios 8 6

html a folder containing the class reference documentation in HTML format README.html a brief description of the SDK with a link to the online documentation Open the appropriate folders and extract the FoglightAPM.framework file. 2 Add FoglightAPM to Xcode. Add the FoglightAPM.framework to your ios app by dragging the file into the Frameworks folder in the Xcode Project Navigator. A dialog box opens. Select the Copy items into destination group's folder check box. 3 Modify the Xcode Linker Settings. In the Xcode Project Navigator pane, click on your project. Under Targets, select your app. Click Build Phases, click Link Binary with Libraries, then click the + icon and add the following libraries: CoreLocation.framework CoreTelephony.framework SystemConfiguration.framework libz.dylib 4 Import. In your application s delegate class, add these import statements: #import <FoglightAPM/FoglightAPM.h> #import <FoglightAPM/FoglightAPMConfig.h> 5 Initialize. Initialize the framework in the didfinishlaunchingwithoptions method of your application delegate. First, set the appropriate properties of the FoglightAPMConfig object with the name of the application and API key. Set the applicationname property to the name of the application that you provided on foglight.com (this name can be different from the name of your app). Set the key property with the value of the API key that was displayed on foglight.com when you created the application. Then, call the startwithconfig method of the FoglightAPM object, as shown in the following code sample. FoglightAPM *foglightapm = [FoglightAPM sharedinstance]; FoglightAPMConfig *config = [FoglightAPMConfig defaultconfig]; config.applicationname = @"MyApp"; config.key = @"fefcbbc9-f439-4ee7-a0a3-dda955d79d60"; [foglightapm startwithconfig:config]; Foglight APM SaaS is now installed in your ios app. Build your app and you can start seeing data in foglight.com within 10 minutes. Next step: Verify that the API is communicating with Foglight APM SaaS. 1 Build your app. 2 Generate a user session by using the app. 3 Log into foglight.com. 4 On the Monitor page, under Applications, verify that your app appears in the list. NOTE: This may take up to 10 minutes, depending on Foglight s collection cycle status. 7

Supported HTTP components Once installed in your app, the Foglight APM SaaS library automatically collects data about the HTTP activity that the app is performing. The Foglight APM SaaS SDK for ios monitors the following frameworks: Foundation Framework AFNetworking 2.0 Supported versions The Foglight APM SaaS library supports ios version 7 and later. Advanced configuration In most cases, the default configuration settings are sufficient. However, there may be advanced behaviors that you want to configure for your app. You can do so by calling methods of the FoglightAPMConfig object, which are then passed to the FoglightAPM.startWithConfig method. The following table lists the methods that are available for advanced configuration. Table 1. FoglightAPMConfig properties Property name Property description Default setting @property BOOL Enable automatic tracking of application Enabled enableautomaticappscreenrecording screens created by VIewControllers. @property BOOL enablecrashtracking Enable or disable automatic crash Enabled tracking @property BOOL enablehttptracking Enable automatic tracking of Enabled NSURLConnection, NSURLSession, and AFNetworking v2.0 classes. @property BOOL enablelocation Enable or disable collection of device location. Enabled @property <list> donottracklist Define a list of matching regular expressions for URLs that the SDK should not track. All URLs are tracked @property String appversion Set the version of the app. No version is reported Figure 2. Sample code - Configure FoglightAPM to block monitoring of URLs ending with.asp FoglightAPM *foglightapm = [FoglightAPM sharedinstance]; FoglightAPMConfig *config = [FoglightAPMConfig defaultconfig]; config.donottracklist = @[@".asp", @"bank"]; [foglightapm startwithconfig:config]; Sample instrumented ios app The following code sample shows how to import, configure, and initialize the Foglight APM SaaS library. It also contains method calls to some commonly-used methods. 8

Figure 3. Code sample Getting started with Foglight APM SaaS SDK for ios #import <FoglightAPM/FoglightAPM.h> #import <FoglightAPM/FoglightAPMConfig.h> @implementation AppDelegate - (BOOL)application:(UIApplication *)application didfinishlaunchingwithoptions:(nsdictionary *)launchoptions { FoglightAPM *foglightapm = [FoglightAPM sharedinstance]; FoglightAPMConfig *config = [FoglightAPMConfig defaultconfig]; config.applicationname = @"MyApp"; config.key = @"aa68961c-533e-4f24-8794-4489d5eba046"; config.appversion = @"2.1.1"; config.donottracklist = @[@".asp", @"bank"]; [foglightapm startwithconfig:config];... } Recording app screens An app screen is a display that the app presents so that the user can interact with the app to accomplish some task or objective. It is analogous to a web page for a traditional web site. In the process of constructing a screen, apps typically perform multiple HTTP requests to back-end web services, to obtain content (such as images or data) that the screen then displays. In an ios app, these screens are typically constructed in a subclass of UIViewController. The Foglight APM SaaS library automatically records app screens by swizzling the viewwillappear and loadview/viewdidappear methods. Any HTTP requests that occur are also automatically tracked and correlated with the app screen. In cases where a screen is displayed without using a ViewController, you need to manually insert calls to the Foglight APM SaaS library to inform it that a screen is being displayed. This can be done with a single method call as shown in the following example. Figure 4. Sample code - recordappscreenstart call example [[FoglightAPM sharedinstance] recordappscreenstart:@"myviewcontroller"]; This creates an app screen in Foglight with a start time and a stop time set to the time the method was called. You may want the start and stop time to correlate more closely to the time at which the content for the screen is ready for display. In that case, you would insert the recordappscreenstart and recordappscreenstop method calls at appropriate points in the code. NOTE: You do not need to disable automatic app screen recording to use these methods. 9

Figure 5. Sample code - recordappscreen and recordappscreenstop calls example [[FoglightAPM sharedinstance] recordappscreenstart:@"myviewcontroller"]; // code to build the screen [[FoglightAPM sharedinstance] recordappscreenstop]; Recording handled exceptions With the Foglight APM SaaS library, you can record exceptions that are handled by the app. To do this, insert a call to the recordexception method at the appropriate point in your code. For example, you can insert this call when an exception is handled, in the exception handler, so that it can be recorded by Foglight. Figure 6. Sample code - recordexception call example @try { // some code performing HTTP requests } catch (NSException *e) { [[FoglightAPM sharedinstance] recordexception:e]; } Tracking crashes A crash is an event that causes the app to halt execution. A typical cause for a crash is an unhandled exception. The Foglight APM SaaS library automatically reports on crashes that occur when the app is running. This is done with a global exception handler that traps unhandled exceptions, the automatic tracking can be disabled by setting FoglightAPMConfig.enableCrashTracking to NO. Hit merging Foglight APM SaaS has the ability to merge and correlate data from multiple sources in the application stack. This allows you to trace and investigate performance problems experienced by front users into your back end application and web servers. For example, if your mobile app makes HTTP requests to a back end REST-style web service where the Foglight Java EE Agent is running, the system merges and correlates data from these two sources dynamically. This facilitates a single unified view of the data for a single HTTP request that crosses multiple application layers where Foglight agents are running. NOTE: Hit merging sometimes does not take place if there are delays in sending data from the mobile app. This can happen if the mobile device temporarily loses its network connection and is unable to transmit to foglight.com for more than one minute. This is most noticeable when viewing hit details that are dependent on the mobile instrumentation, such as Device Type. These hit details would appear as Unknown in the user interface. 10

About Dell Dell listens to customers and delivers worldwide innovative technology, business solutions and services they trust and value. For more information, visit www.software.dell.com. Contacting Dell Technical support: Online support Product questions and sales: (800) 306-9329 Email: info@software.dell.com Technical support resources Technical support is available to customers who have purchased Dell software with a valid maintenance contract and to customers who have trial versions. To access the Support Portal, go to https://support.software.dell.com/. The Support Portal provides self-help tools you can use to solve problems quickly and independently, 24 hours a day, 365 days a year. In addition, the portal provides direct access to product support engineers through an online Service Request system. The site enables you to: Create, update, and manage Service Requests (cases) View Knowledge Base articles Obtain product notifications Download software. For trial software, go to Trial Downloads. View how-to videos Engage in community discussions Chat with a support engineer 11