This page applies to an earlier version of the AppDynamics App IQ Platform.
For documentation on the latest version, see the 4.4 Documentation.


On this page:

Watch the video:

Start Monitoring with the iOS Agent

Your Rating:
Results:
PatheticBadOKGoodOutstanding!
53 rates

Use this method to have CocoaPods manage your dependencies.

1. Access the instrumentation window

  1. Open the application in which you are interested. This can be an instrumented server-side application with which your mobile app interacts or a "container" application that holds your mobile application's information in the Controller UI.
  2. On the left navigation bar,  click Configuration.
  3. Select Instrumentation > End User Monitoring.
  4. Click the Mobile Apps tab.

2. 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.

3. Set Up Your Podfile

  1. Add this line to your Podfile:

    pod 'AppDynamicsAgent'
  2. In your project directory, run this command:

    pod install

4. Initialize the Agent - Objective C

 Click here to expand...

Edit your app's AppDelegate 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 AppDelegate.m file, add this import:

    #import <ADEUMInstrumentation/ADEumInstrumentation.h>
  2. In AppDelegate, add a call to initialize the SDK using didFinishLaunchingWithOptions. Use the SDK ADEumInstrumentation method initWithKey passing in your application key, recorded in step 2, as a parameter by adding this line of code:

    [ADEumInstrumentation initWithKey:@"<APPLICATION_KEY_FROM_STEP_TWO>"];

    Your code should look something like this:

    #import <ADEUMInstrumentation/ADEUMInstrumentation.h>
    #import "AppDelegate.h"
     
            // ...
             -(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
            {
                [ADEumInstrumentation initWithKey:@"<APPLICATION_KEY_FROM_STEP_TWO>"]; // for example, EUM-AAB-AUM
                // other tasks
                return YES;
            }
  3. Save the file.

4A. Initialize the Agent - SWIFT

 Click here to expand...

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

  1. Create a bridging header, as described in this Apple document, 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("<APPLICATION_KEY_FROM_STEP_TWO>")

    using the application key from step 2, for example, EUM-AAB-AUM.

  4. Save the file.

4B. Initialize the Agent - Apple Watch Extensions

 Click here to expand...

Apps written for watchOS 1 contain a WatchKit extension that runs on the user's iPhone, but watchOS 2 also supports a new architecture, where the WatchKit extension runs on the Apple Watch itself. AppDynamics supports the watchOS 1 architecture, but not the new watchOS 2 architecture. Note that apps using the watchOS 1 architecture can run on both watchOS 1 and 2, so if your application is designed for watchOS 1, you can use AppDynamics on both versions of watchOS.

Because watchOS 1 apps are functionally launched in response to an interaction with the Watch UI, the SDK initialization code should be called at the point of that interaction in the iPhone app, which is usually not at the extension's AppDelegate.m call. The syntax remains the same.

5. Enable dSYM file.

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 enable dSYM

  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".

The AppDynamics iOS SDK does not currently include bitcode. While bitcode will be coming in a future release, if you are using Xcode 7, you will need to set ENABLE_BITCODE to NO in order to build your application. See this StackOverflow article for more information.

6. 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.

You can:

Upload the dSYM File to AppDynamics Automatically with Each Build

 Click here to expand...

Automating the upload of your dSYM file reduces the number of manual steps required with each build, and ensures that all builds have appropriate dSYM files available for AppDynamics to use.

  1. In Xcode, select your project from the Project Navigator.
  2. Click on the Application Target
  3. Select the Build Phase tab in the Settings editor
  4. Click the + icon in the upper left corner of the main panel
  5. Select New Run Script Phase from the dropdown box.
  6. In the script box, add the following lines:

    export ADRUM_ACCOUNT_NAME="<Account_Name_HERE>" // From the View License - End User Monitoring section of the License Page
    export ADRUM_LICENSE_KEY="<License_Key_HERE>"  // From the View License - End User Monitoring section of the License Page
    SCRIPT=`/usr/bin/find "${SRCROOT}" -name xcode_build_dsym_upload.sh | head -n 1`
    /bin/sh "${SCRIPT}"
  7. There are also some optional parameters you can set if desired.  To set them, add the following line(s) after the second export statement above.

    export ADRUM_UPLOAD_WHEN_BUILT_FOR_SIMULATOR=0
    export ADRUM_TREAT_UPLOAD_FAILURES_AS_ERRORS=0
    export ADRUM_EUM_PROCESSOR="<EUM_SERVER_URL>"

    The last statement should be used to set the URL for an on-prem version of the EUM Server.

  8. Rebuild.

Upload the dSYM File to AppDynamics Manually

  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 Report 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

 Click here to expand...
  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

 Click here to expand...

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.

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 EUM account name>:<URL-encoded EUM 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>"

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

7. 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 five basic kinds of extensions that you can create:

  • custom timers
  • custom metrics
  • user data
  • information points
  • breadcrumbs

In addition, if you are using an environment with an on-premise EUM Server, you need to update your code to indicate the URL to which your agent should send its beacons.  You can also set up the agent to use a custom HTTP library.

For more information, see Use the APIs of the iOS SDK to Customize Your Instrumentation.

Conflicts/Compatibility

There are currently no documented cases of conflicts with other third-party libraries/tools that might also be used in your application.  However any tool that does crash reports is likely to be incompatible with the AddDynamics iOS SDK.

Upgrade the iOS Mobile Agent

  1. In your project directory, run this command:

    pod update
  2. Rebuild.

App Transport Security (ATS), iOS 9, and On-Premise EUM Servers

If you use an on-premise EUM Server and you wish to use HTTP to dispatch your beacons to the Server, starting with iOS 9 you need to set a flag in your app's info.plist file to allow it to use the unsecured connection.  By default HTTPS is enforced in all iOS 9 applications by App Transport Security. For more detailed information, see this Apple Technote.

  • No labels