Instruments Quick Start

Instruments is a powerful tool you can use to collect data about the performance and behavior of one or more processes on the system and track that data over time. Unlike most other performance and debugging tools, Instruments lets you gather widely disparate types of data and view them side by side. In this way you can spot trends that might otherwise be hard to spot with other tools. For example, your app may have large memory growth that is caused by multiple network connections being opened. Using the Allocations and Connections instruments together, you can pinpoint those connections that are not closing and so are causing the rapid memory growth.

The Instruments tool uses individual data collection modules known as instruments to collect data about a process over time. Each instrument collects and displays a different type of information, such as file access, memory use, and so forth. Instruments includes a library of standard instruments, which you can use as is to examine various aspects of your code. You can configure instruments to gather data about the same process or about different processes on the system. You can build new instruments using the custom instrument builder interface, which uses the DTrace program to gather the data you want.

All work in Instruments is done in a trace document, which contains a set of instruments and the data they collected. Each trace document typically holds a single session’s worth of data, which is also referred to as a single trace. You can save a trace document to preserve the trace data you have gathered and open them again later to view that data.

Although most instruments are geared toward gathering trace data, the User Interface instrument helps automate data collection. With it you can record user events while you gather your trace data. You can use this recording to reliably reproduce the same sequence of events over and over again. Each time you run through this sequence, your trace document gathers a new set of trace data from the other instruments in the document and presents that data side by side with previous runs. This feature lets you compare trace data as you make improvements to your code and verify that the changes you make are having the desired impact.

Launching Instruments

Instruments is contained within the Xcode 4 toolset. Download Xcode from the App Store and install it onto your computer. After you have installed Xcode, you are ready to run Instruments. Instruments can be launched in one of three ways.

To run Instruments from Xcode
  1. Open Xcode.

  2. Choose Xcode > Open Developer Tool > Instruments.


Running Instruments from your code allows you to gather information about your app every time you build it. Incorporating Instruments from the beginning of the app development process can save you time later by finding issues early in the development cycle.

To run Instruments while building your code
  1. Open the scheme editor.

  2. Select Edit Scheme.

  3. Select Profile app name.

  4. Choose an instrument template from the Instrument pop-up menu.

    The default choice is “Ask on Launch,” which causes Instruments to display its template chooser dialog when it starts up.

The third way to run Instruments can be achieved only after you have launched Instruments from Xcode. Save Instruments to the Dock, so that you are able to quickly run Instruments in the future without opening Xcode.

To run Instruments from the Dock
  1. Launch Instruments from Xcode using one of the two options above.

  2. Control-click the Instruments icon in the Dock.

  3. Click Options > Keep in Dock.


Gathering Your First Data

Even though each instrument is different, there is one general workflow when collecting information from your app. This workflow is a four-step process. You:

  1. Choose a trace template

  2. Direct Instruments to your app

  3. Collect information from about your app

  4. Examine the collected information

Choose a Trace Template

When Instruments first starts up, it provides you with a list of trace templates. These templates contain collections of individual instruments that are used together to provide you with a specific set of information. For Figure 1-1, the Multicore trace template is selected.

Figure 1-1  The Instruments Trace Template selection window

Choose Your Target

If you did not start Instruments while compiling your code, you must select a target for the instruments chosen. A target can be an app or a process that is already running. Some instruments allow you to gather information from all of the running processes on your device. In Figure 1-2, the Chess app is chosen.

Figure 1-2  Selecting the Chess app as the target

Collect and Examine the Data

Now that you have chosen the trace template and target for your app, it is time to collect the data. You can adjust the information that is collected by an instrument through its configuration dialog. Figure 1-3 shows data collection using the default values for the two instruments. Click Record to start collecting data. When you have enough data, click Stop.

After collecting your data, you are able to examine it through the Detail pane. Selecting a row in the Detail pane brings up extra information on the row in the Extended Detail pane.

Figure 1-3  Collecting information with the Multicore trace template