Instruments Tutorial with Swift: Getting Started

In addition to improving their apps by adding features, there’s one thing all good app developers should do: instrument their code! This Xcode Instruments tutorial will show you how to use the most important features of the Instruments tool that ships with Xcode.

In this tutorial, you’ll learn:

• What Instruments is and what tools it contains
• Ways of configuring and customizing your instruments
• How to check your code for performance issues, memory issues, reference cycles and other problems
• The best way to debug these issues

You’ll do this by going through an existing app and improving it using Instruments — much like you would with your own apps!

Getting Started

Download the project materials using the Download Materials button at the top or bottom of this tutorial.

This sample app uses the Flickr API to search for images. To use the API, you need an API key. For demo projects, you can generate a sample key on Flickr’s website:

1. Go to https://identity.flickr.com and either create a new Flickr account, or sign in with your existing account.
2. Once signed in successfully, go to Flickr API Explorer.
3. Find and click Call Method… at the bottom of the page.
4. This will generate a URL link at the very bottom of the page that looks like:

   https://www.flickr.com/services/rest/?method=flickr.photos.search
   &api_key=f0589d37afc0e29525f51ccb26932a06
   &format=rest
   &auth_token=72157717064637163-20d89cb35333d1eb
   &api_sig=80ada3ca6dba49f7fcc9ced2743de537
   

5. Copy the API key from the URL. You can find this by looking for the number between &api_key= and the next & you see. In the above example, the API key is f0589d37afc0e29525f51ccb26932a06.

https://www.flickr.com/services/rest/?method=flickr.photos.search
&api_key=f0589d37afc0e29525f51ccb26932a06
&format=rest
&auth_token=72157717064637163-20d89cb35333d1eb
&api_sig=80ada3ca6dba49f7fcc9ced2743de537

To update the project, open FlickrAPI.swift and replace the existing API key value with your new value.

Build and run, perform a search, click the result and you’ll see something like this:

Play with the app and check out its basic functions. You might think that once the UI looks great, the app is ready for store submission. But you’re about to see the value that using Instruments can add to your app.

The rest of this tutorial shows you how to find and fix issues that still exist in the app. You’ll see how Instruments can make debugging problems much easier!

Time for Profiling

The first instrument you’ll look at is Time Profiler. At measured intervals, Instruments halts the execution of the program and takes a stack trace on each running thread. Think of it as clicking the pause button in Xcode’s debugger.

Here’s a sneak preview of Time Profiler:

This screen displays the Call Tree. The Call Tree shows the amount of time spent executing various methods within an app. Each row is a different method the program’s execution path has followed. The Instruments tool approximates the time spent in each method by counting the number of times the profiler stops in each method.

For instance, if you take 100 samples at 1 millisecond intervals and a particular method appears at the top of the stack in 10 samples, you can deduce that the app spent approximately 10% of the total execution time — 10 milliseconds — in that method. It’s a crude approximation, but it works!

So without any further ado, time to get instrumenting!

Instrumenting

From Xcode’s menu bar, select Product ▸ Profile or press Command-I. This builds the app and launches Instruments. You’ll see a selection window like this:

These are all different templates that come with Instruments.

Select the Time Profiler instrument and click Choose to open a new Instruments document. Click the record button at the top left to start recording and launch the app. macOS may ask for your password to authorize Instruments to analyze other processes. Fear not, it’s safe to provide here!

In the Instruments window, you can see the time counting up and a little arrow moving from left to right above the graph in the center of the screen. This indicates the app is running.

Now, start using the app. Search for some images, and drill down into one or more of the search results. You’ll notice that going into a search result is slow, and scrolling through a list of search results is annoying. It’s a clunky app!

Well, you’re in luck, as you’re about to embark on fixing it! But you’re first going to get a quick rundown of what you’re looking at in Instruments.

Make sure you have all the detail views open by toggling the view selectors on the right-hand side of the toolbar:

That ensures all panels are open. Now, study the screenshot below:

Here’s what you’re seeing:

At the top of the detail panel, click Profile and select Samples.

Here you can view every single sample. Click on a few samples; you’ll see the captured stack trace appear in the Extended Detail inspector to the right. Switch back to Profile when you’re done.

1. Recording controls: The record button stops and starts the app currently under test. The pause button pauses the current execution of the app.
2. Run timer: The timer counts how long the profiled app has been running and how many times it has run. The above screenshot is the second run, Run 2 of 2.
3. Instrument track: This is the Time Profiler track. You’ll learn more about the specifics of the graph later in the tutorial.
4. Detail panel: This shows the main information about the particular instrument you’re using. In this case, it shows the ones using the most CPU time.

   At the top of the detail panel, click Profile and select Samples.

   

   Here you can view every single sample. Click on a few samples; you’ll see the captured stack trace appear in the Extended Detail inspector to the right. Switch back to Profile when you’re done.

5. Inspectors panel: There are two inspectors — Extended Detail and Run Info — which you’ll learn more about shortly.

Now that you have an overview, it’s time to dig in some more!