Get Started with Firebase Performance Monitoring for iOS

This guide shows you how to use Firebase Performance Monitoring with your app, following these steps:

  1. Prerequisites
  2. Add Firebase to your iOS project
  3. Add Performance Monitoring to your app
  4. (Optional) Define a custom trace and one or more custom metrics in your app
  5. Check the Firebase console for Performance Monitoring results
  6. Deploy your app and review results in the Firebase console

Prerequisites

Before you begin, you need a few things set up in your environment:

  • Xcode 8.2.1 or later
  • An Xcode project targeting iOS 8 or above
  • The bundle identifier of your app
  • CocoaPods 1.0.0 or later

Add Firebase to your iOS project

Next, you need to add Firebase to your app, add the SDK, and initialize Firebase in your app. For instructions, see Add Firebase to your iOS project.

Add Performance Monitoring to your app

  1. Open the podfile you created for the project (or create one using the pod init command), and then add the following lines inside the target section:
    pod 'Firebase/Core'
    pod 'Firebase/Performance'
  2. In the directory where your podfile is located, run the following command to install the Performance Monitoring SDK:
    pod install
  3. At the end of the command, open the .xcworkspace file using Xcode.
  4. Import the Firebase module in your UIApplicationDelegate:

    Swift

    import Firebase
    

    Objective-C

    @import Firebase;
    
  5. Configure a FirebaseApp shared instance, typically in your application's application:didFinishLaunchingWithOptions: method:

    Swift

    // Use Firebase library to configure APIs
    FirebaseApp.configure()
    

    Objective-C

    // Use Firebase library to configure APIs
    [FIRApp configure];
    
  6. Recompile your app. Automatic traces and HTTP/S network requests are now monitored.

(Optional) Define a custom trace and one or more custom metrics in your app

A custom trace is a report of performance data associated with some of the code in your app. To learn more about custom traces, see the Performance Monitoring overview. You can have multiple custom traces in your app, and it is possible to have more than one custom trace running at a time. Each custom trace can have one or more metrics to count performance-related events in your app, and those metrics are associated with the traces that create them.

  1. Add the Performance Monitoring module to your header:

    Swift

    import FirebasePerformance

    Objective-C

    @import FirebasePerformance;

  2. Just before the code where you want to start a trace in your app, add the following lines of code to start a trace called test trace:

    Swift

    let trace = Performance.startTrace(name: "test trace")

    Objective-C

    FIRTrace *trace = [FIRPerformance startTraceWithName:@"test trace"];

  3. To count performance-related events that occur in your app (such as cache hits or retries), add a line of code similar to the following each time that the event occurs, using a string other than retry to name that event if you are counting a different type of event:

    Swift

    trace.incrementMetric(named:"retry", by: 1)

    Objective-C

    [trace incrementMetric:@"retry" by:1];

  4. Just after the code where you want to stop your trace, add the following line of code:

    Swift

    trace.stop()

    Objective-C

    [trace stop];

Check the Firebase console for Performance Monitoring results

  1. Run your app in the Xcode simulator (Product -> Run).
  2. Confirm that Performance Monitoring results appear in the Firebase console. Results should appear within 12 hours.

Deploy your app and review results in the Firebase console

After you have validated Performance Monitoring using the Xcode simulator and one or more test devices, you can deploy the updated version of your app to your users and use the Firebase console to monitor performance data.

(Optional) Add monitoring for specific network requests

Performance Monitoring collects network requests automatically. Although this includes most network requests for your app, some might not be reported. To include specific network requests in Performance Monitoring, add the following code to your app:

Swift
guard let metric = HTTPMetric(url: "https://www.google.com", httpMethod: .get) else { return }

metric.start()
guard let url = URL(string: "https://www.google.com") else { return }
let request: URLRequest = URLRequest(url:url)
let session = URLSession(configuration: .default)
let dataTask = session.dataTask(with: request) { (urlData, response, error) in
        if let httpResponse = response as? HTTPURLResponse {
         metric.responseCode = httpResponse.statusCode
        }
        metric.stop()
}
dataTask.resume()
Objective-C
@property (nonatomic) FIRHTTPMetric *metric;
...
- (void)beginManualNetworkInstrumentation {
  self.metric =
      [[FIRHttpMetric alloc] initWithURL:[NSURL URLWithString:@"https://www.google.com"]
                              HTTPMethod:FIRHTTPMethodGET];

  [self.metric start];

  NSURLRequest *request =
      [NSURLRequest requestWithURL:[NSURL URLWithString:@"https://www.google.com"]];
  NSURLConnection *connection = [[NSURLConnection alloc] initWithRequest:request
                                                                delegate:self];
  [connection resume];
}

- (void)connection:(NSURLConnection *)connection
    didReceiveResponse:(NSURLResponse *) response {
  NSHTTPURLResponse* httpResponse = (NSHTTPURLResponse*)response
  self.metric.responseCode = httpResponse.statusCode;
  [self.metric stop];
}

The HTTP/s network requests you specifically capture this way appear in the Firebase console along with the network requests Performance Monitoring captures automatically.

(Optional) Review a sample of traces and network requests

You can deep dive into segments of specific traces or network requests in the Firebase console. A random sampling of recorded sessions shows the following information:

an image of the Firebase Performance Monitoring sessions page

  • CPU: The Performance Monitoring SDK captures how much user time and system time your app consumes.
  • Memory: The Performance Monitoring SDK captures how much heap memory your app uses. Heap memory is the memory used for dynamic allocations, including objects created, objects deallocated, and objects that the app is actively using.
  • Individual information: Detailed information about a single instance of a trace or network request, including start time, end time, duration, request size, and response size.
  • Concurrent instances: Information about traces or network requests that happened at the same time.
  • Device attributes: Information about the device, including app version, model, OS version, radio, and custom attributes.

To see these detailed samples in the Firebase console, open one of your app's traces or network requests and click See sessions. Alternatively, click the link for an attribute's sessions from the specific attribute.

an image of the Firebase Performance Monitoring trace with a link to sessions

The sessions Performance Monitoring collects are distributed into percentiles for each metric. Sessions in lower percentile ranges have a lower value for the metric than sessions in higher percentile ranges. To filter the available sessions by percentile, use the percentiles dropdown above the sessions details.

an image of the Firebase Performance Monitoring sessions page

Known issues

  • Performance Monitoring has known compatibility issues with GTMSQLite. We recommend not using Performance Monitoring with apps that use GTMSQLite.
  • Method swizzling after calling FirebaseApp.configure() might interfere with the Performance Monitoring SDK.
  • Known issues with the iOS 8.0-8.2 Simulator prevent Performance Monitoring from capturing performance events. These issues are fixed in the iOS 8.3 Simulator and later versions.
  • Connections established using NSURLSession's backgroundSessionConfiguration will exhibit longer than expected connection times. These connections are executed out-of-process and the timings reflect in-process callback events.

Next steps

Send feedback about...

Need help? Visit our support page.