AppDynamics Application Intelligence Platform

3.9.x Documentation

PDFs

Learn by Watching

Doc Maps

  • Created by Unknown User (delling@appdynamics.com), last modified by Unknown User (ellen.evans@appdynamics.com) on Oct 01, 2014

Watch a quick video overview of the main steps of the process.
 

Direct link: https://appdynamo.wistia.com/medias/pohgsjj2dd

1. Access the instrumentation window

  1. In the left navigation bar, select the application that you have enabled.
    This is either the server-side instrumented application that your mobile application communicates with or an application that you have created manually. 
  2. On the left nav bar,  click Configure -> Instrumentation.
  3. Click the End User Experience tab.
  4. Click the Mobile Apps subtab.

2. Download the iOS SDK

Click the iOS SDK link in step .  This downloads a file named iOSAgent.zip.

You must download the SDK separately for each application that you instrument.

3. Record Your Application Key

Record the application key generated for this application, displayed in step .

You will need this key when you modify the source code.

4. Install the Framework

Uncompress the .zip file you downloaded: you have a file named ADEUMInstrumentation.framework.  Drag this framework file into your project's Frameworks directory.

5. Modify the Application Source Code - Objective C

Edit your app's main.m file to initialize the mobile agent as soon as the app launches.  This registers your application, and only needs to be done once in your code.

  1. In your application's main.m, add this import:

    #import <ADEUMInstrumentation/ADEUMInstrumentation.h>

  2. Add the call to ADEumInstrumentation initWithKey passing your application key, recorded in step 3, as a parameter by adding this line of code to the beginning of your application's main() function:

    [ADEumInstrumentation initWithKey:@"$CURRENT_APP_KEY"];

    Your main.m should look something like this:

    #import <UIKit/UIKit.h>
#import <ADEUMInstrumentation/ADEUMInstrumentation.h>
#import "AppDelegate.h"

int main(int argc, char *argv[])
{
    [ADEumInstrumentation initWithKey:@"$CURRENT_APP_KEY"];
    @autoreleasepool {
        return UIApplicationMain(argc, argv, nil, NSStringFromClass([AppDelegate class]));
    }
}
  3. Save the file.

5A. Modify the Application Source Code - SWIFT

The iOS Agent is compatible with applications created using the Swift programming language.  

  1. Create a bridging header, as described in this Apple documentation, to expose the Agent's Objective C code to your Swift code.  

  2. To your bridging header, add this code:

    #import <ADEUMInstrumentation/ADEUMInstrumentation.h>

  3. In your main.swift or AppDelegate's didFinishLaunchingWithOptions, initialize the SDK like this:

    ADEumInstrumentation.initWithKey($CURRENT_APP_KEY")

  4. Save the file.

6. Add Required Libraries, as Necessary

The Appdynamics iOS agent requires the following libraries:

  • SystemConfiguration.framework
  • CoreTelephony.framework
  • libz.dylib
  • libsqlite3.dylib

To add the libraries

  1. Select the target that builds your app in Xcode.
  2. Select the Build Phases tab.
  3. Expand the Link Binary With Libraries section.
  4. If any of the above libraries are not listed:
  • Click the + button.
  • Locate the missing library in the list.
  • Click Add. 

Repeat this step for each missing library.

7. Rebuild You Application

Rebuild your application with the modified application code.

To enable the agent to provide human-readable information in the crash snapshots that are produced if the application crashes, compile with the DWARF with dSYM file option to create a debug symbols file for the application. For more details about why you would want to do this see Get Human-Readable Crash Snapshots.

To rebuild your application

  1. In Xcode, select your project in the Project Navigator.
  2. In the target list, select the target that builds your application.
  3. Select the Build Settings tab.
  4. In the Build Options section, make sure that the Debugging Information Format is set to "DWARF with dSYM File".

  5. Rebuild the Xcode project.

8. Upload the dSYM File

This step is optional but highly recommended if you plan to monitor crashes. AppDynamics needs the dSYM file for the application to produce human-readable stack traces for crash snapshots.

For details about why you should do this, see Get Human-Readable Crash Snapshots.

(warning) If you update the application, you need to provide the new dSYM file for the new application version. The dSYM file contains an UUID that links it to a specific Xcode build, so AppDynamics can unambiguously match the correct dSYM file with an incoming crash report with no additional information.

  1. Get the dSYM file from Xcode
  2. Upload the dSYM file to AppDynamics using the UI
    or
    Upload the dSYM File to AppDynamics Using the API

Get the dSYM file from Xcode

  1. In Xcode, run the Xcode build: Product > Build.
  2. View the log navigator: View > Navigators > Show Log Navigator.
  3. Click the log entry for the most recent build.
  4. Near the end of the log, find and mouse over the log entry named "Generate <Your_App_Name>.app.dSYM".
  5. Click the button on the right side of the entry you found in step #4 to expand it.
    The end of the displayed command is the path to the dSYM file.
  6. Navigate to this dSYM file in the Finder.
  7. Right click on the dSYM file and choose Compress.
  8. Upload to AppDynamics the .zip file that Finder generates.

Upload the dSYM file to AppDynamics using the UI

  1. In the instrumentation window in the controller UI, click the Upload dSym package file for iOS crashes button.
  2. In the Xcode dSym package upload window click Select zipped dSym file.
    The uploader expects a file with a .zip extension.
  3. In the file browser locate the zipped dSYM file for the application that you are instrumenting and click Open.
  4. Click Upload.

Upload the dSYM File to AppDynamics Using the REST API

The API uses HTTP basic authentication to send a PUT request to AppDynamics. The username is your AppDynamics account name and the password is your EUM license key.

1. Set up your HTTP basic authentication credentials

  1. In the upper right section of the Controller UI, click Settings -> License.
  2. Scroll down to the End User Experience Management panel.
  3. Note the Account Name at the top of the panel. This is your username for authentication.
  4. Note the License Key just below the Account Name. This is your password for authentication.

  5. URL-encode the account name and the license key.
  6. Generate an authentication string of the form: "<URL-encoded EUEM account name>:<URL-encoded EUEM license key>" and base64 encode it. You will use this string the following step.
  7. Add an authentication header to each request, setting its value to "Basic <authentication string>"

2. Send the dSYM file

Send the dSym as a zip archive in the body of a PUT request to the following URI:

https://api.eum-appdynamics.com/eumaggregator/crash-reports/iOSDSym

The content type of the body must be application/zip if the file is a zip file or application/gzip if it is a gzip file. Only these formats are accepted.

Sample Request and Response Using the REST API

This is a sample request and response using the REST API.

Upload Request

The following example uses curl to send a dSym file named UISampleApp.app.dSYM.zip. The account name is "Example account " and the license key/password is Example-License-Key-4e8ec2ae6cfe. The plus signs replace spaces in the account name when the account name is URL-encoded.

curl -v --upload-file UISampleApp.app.dSYM.zip --user Example+account:Example-License-Key-4e8ec2ae6cfe https://api.eum-appdynamics.com/eumaggregator/crash-reports/iOSDSym

Upload Response

The successful output of the sample request looks like this:

* About to connect() to api.eum-appdynamics.com port 443 (#0)*   Trying ::1...
* connected
* Connected to api.eum-appdynamics.com (::1) port 443 (#0)
* Server auth using Basic with user 'Example+account'
> PUT /eumaggregator/crash-reports/iOSDSym HTTP/1.1
> Authorization: Basic SW50ZXJuYWwrdGVzdCthY2NvdW50OlRlc3RBY2N0LTFlMzktNDVkMy05MzAzLTRlOGVjMmFlNmNmZQ==
> User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8y zlib/1.2.5
> Host: localhost:7001
> Accept: */*
> Content-Length: 0
> Expect: 100-continue
>
< HTTP/1.1 100 Continue
< HTTP/1.1 200 OK
< Content-Length: 0
< Server: Jetty(8.1.4.v20120524)
<
* Connection #0 to host api.eum-appdynamics.com left intact
* Closing connection #0

9. Customize Your Instrumentation (Optional)

 The ADEUMInstrumentation class has additional methods to allow you to extend the kinds of data you can collect and aggregate using AppDynamics.  There are three basic kinds of extensions that you can create:

  • custom timers
  • custom metrics
  • information points

In addition, if you are using an environment with an on-premise version of the EUEM Processor, you need to update your code to indicate the URL to which your agent should send its beacons.

For more information, see Customize Your iOS Mobile Instrumentation.