AppDynamics iOS SDK Version: 2022.3.0 Reference

About the AppDynamics iOS SDK

The AppDynamics iOS SDK is a framework that allows you to monitor the performance and activities of an iOS application as it runs.

It will automatically detect and instrument HTTP requests that the enclosing application sends via NSURLConnection or NSURLSessions or any framework that uses these objects.

The SDK also provides a facility to track any application crashes that occur.

The SDK includes APIs to instrument specific methods in your own code, to measure durations of operations in your application (like application start up, for example), or to report an arbitrary metric.

If you have an on-premise deployment, please note that some of the features described here require a minimum EUM server deployment version. Please refer to the Mobile Agent Version and Deployment Support Matrix for more information.

Quick install

There are two ways to include the AppDynamics iOS SDK in your application.

CocoaPods

If your project uses CocoaPods then you can simply add the following to your Podfile:

pod 'AppDynamicsAgent'

Then run the this command:

pod install

Manual Method

Follow these steps:

  1. Link your project against EUMInstrumentation.framework. The easiest way to do this is to drag the EUMInstrumentation.framework bundle into your project’s Frameworks group in Xcode.

  2. Add a call to initialize the SDK in the -[UIApplicationDelegate application:didFinishLaunchingWithOptions:] method. This method will be called when your application starts up. It looks something like:

     - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
         [ADEumInstrumentation initWithKey:@"<#YOUR APP KEY HERE#>"];
         // other tasks
         return YES;
     }
    

    If you don’t know your app key, see the documentation.

  3. Link your project against the following libraries:

    • SystemConfiguration.framework
    • CoreTelephony.framework
    • libz.dylib
  4. Add -ObjC to the Other Linker Flags in your Build Settings.

Instrumenting methods

While the AppDynamics iOS SDK instruments some system method automatically, you can also use it to instrument methods in your own code. When you do this, you’ll be able to see how often the instrumented method is invoked, and how long it takes to run. To do this, add a call at the beginning and end of the method you’d like to instrument:

- (void)startTimerWithName {
    id tracker = [ADEumInstrumentation beginCall:self selector:_cmd];

    // Implementation of method here ...

    [ADEumInstrumentation endCall:tracker];
}

Timing events

Sometimes you want to time an event in your application that spans multiple methods. You can do this by calling the SDK when the event starts, and then again when it ends. For example, to track the time a user spends viewing a screen, the instrumentation looks like:

- (void)viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];
    [ADEumInstrumentation startTimerWithName:@"View Lifetime"];
}

- (void)viewDidDisappear:(BOOL)animated {
    [super viewDidDisappear:animated];
    [ADEumInstrumentation stopTimerWithName:@"View Lifetime"];
}

Reporting metrics

If you’d like to report some other type of data, you can use a metric. The only requirement is that the metric value must be an integer. Reporting a metric looks like this:

[ADEumInstrumentation reportMetricWithName:@"My custom metric" value:<#VALUE HERE#>];

Reporting custom HTTP requests

While the SDK can automatically discover HTTP requests made through the Objective-C system libraries, you might be using some other HTTP library that the SDK doesn’t automatically instrument. In that case, you can explicitly report your HTTP requests.

Suppose you have a method like this for making HTTP requests:

- (NSData *)sendRequest:(NSURL *)url error:(NSError **)error {
    // implementation omitted

    NSData *result = nil;
    if (errorOccurred) {
        *error = theError;
    } else {
        result = responseBody;
    }
    return result;
}

Here’s how you would augment this method to report requests to the SDK:

- (NSData *)sendRequest:(NSURL *)url error:(NSError **)error {
    ADEumHTTPRequestTracker *tracker = [ADEumHTTPRequestTracker requestTrackerWithURL:url];
    // implementation omitted

    NSData *result = nil;
    if (errorOccurred) {
        *error = theError;
        tracker.error = theError;
    } else {
        tracker.statusCode = theStatusCode;
        tracker.allHeaderFields = theResponseHeaders;
        result = responseBody;
    }
    [tracker reportDone];
    return result;
}

Automatic Instrumentation Notes

Automatic instrumentation is achieved by using:

  1. Wrapper objects that are subclassed from NSProxy.
  2. The use of ObjectiveC Categories to extend classes of interest.
  3. Method “swizzling” that interpose methods of interest.

All mechanisms used are well documented, safe and “stackable” when used correctly. In the interest of full disclosure, here is a list of objects and methods that we swizzle:

  1. NSURLConnection:
    1. -initWithRequest:delegate:
    2. -initWithRequest:delegate:startImmediately:
    3. -start
    4. +sendSynchronousRequest:returningResponse:error:
    5. +connectionWithRequest:delegate:
    6. +sendAsynchronousRequest:queue:completionHandler:
  2. NSURLSession:
    1. +sharedSession
    2. +sessionWithConfiguration:
    3. +sessionWithConfiguration:delegate:delegateQueue:
  3. NSURLRequest:
    1. -initWithURL:cachePolicy:timeoutInterval:
    2. -mutableCopyWithZone:
  4. UIApplication:
    1. -setDelegate:
    2. -sendAction:to:from:forEvent:
    3. -sendEvent
  5. UIApplicationDelegate:
    1. applicationWillResignActive:
    2. applicationDidBecomeActive:
    3. applicationWillEnterForeground:
    4. applicationDidEnterBackground
  6. UIViewController:
    1. -viewDidAppear:
    2. -viewWillDisappear:
    3. -loadView

Further Documentation

For a more detailed description of how to use SDK, or for troubleshooting information, please see the official documentation