Instruments User Guide

Instruments Quick Start

Instruments is a powerful tool you can use to collect data about the performance and behavior of a process 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 identify trends that might otherwise be hard to spot with other tools. For example, your app may exhibit large memory growth that is caused by multiple network connections being opened. Using the Allocations and Connections instruments together, you can identify the connections that are not closing and resulting in 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 configure and use to examine various aspects of your code. You can also build your own custom instruments that use DTrace to gather other kinds of data.

Note: Several Apple apps—namely, iTunes, DVD Player, and apps that use QuickTime—prevent the collection of data through DTrace in order to protect sensitive or copyrighted data.

All work in Instruments is done in a trace document, which contains a set of instruments and the data they collected. You can save a trace document to preserve the trace data you have gathered and open it again later to view that data.

Launching Instruments

Instruments is contained within the Xcode toolset, which can be installed through the App Store. After you have installed Xcode, Instruments can be launched in one of three ways.

To run Instruments from Xcode

Open Xcode.

Choose Xcode > Open Developer Tool > Instruments.

Incorporating Instruments into your workflow from the beginning of the app development process can save you time later by helping you find issues early in the development cycle. The ability to initiate Instruments directly from within Xcode allows you to gather information about your app regularly, such as every time you build it.

To run Instruments while building your code

Select Edit Scheme in the scheme menu in the Xcode toolbar.

Click Profile in the scheme editor sidebar.

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. You can, of course, select a specific instrument profiling template here instead, if you prefer.

Click Close.

Hold down the Run button in the Xcode toolbar and choose Profile or choose Profile from the Product menu whenever you want to build your app and run it in Instruments.

The third way to open Instruments is from the Dock. To do this, you need to first open Instruments using one of the methods listed above and configure it to stay in the Dock.

To run Instruments from the Dock

Launch Instruments from Xcode using one of the two methods above.

Control-click the Instruments icon in the Dock.

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. You:

Open Instruments.

Choose a target device and app.

Choose a trace template.

Collect information from your app.

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 instruments that are commonly used together to provide you with a specific set of information. Optionally, you may specify a target device and app at the top of the template selection window. In Figure 1-1, the Time Profiler trace template is selected and an app named Sketch is selected as the target app.

Figure 1-1 The Instruments trace template selection window

Choose Your Target

If you didn’t launch Instruments from the Xcode Product menu or Run button, or select a target from the template selection window, then you need to specify a target for the instruments in the trace document to profile. A selected target may be an installed app, such as Chess in Figure 1-2, or a process that is already running.

Figure 1-2 Selecting the Chess app as the target

Tip: Some instruments, such as Activity Monitor and Time Profiler, allow you to gather information from all of the running processes on your device.

Collect and Examine the Data

Once you have created a trace template and chosen a target for your app, it’s time to collect some data. You can adjust the information that’s collected by an instrument via the Record Settings area in the Inspector sidebar. Click Record to start collecting data. When you have enough, click Stop. Figure 1-3 shows data collected from the Sketch app using the Time Profiler template.

After collecting your data, you can examine it in the detail pane, as well as the Extended Detail area in the Inspector sidebar. Select a row in the detail pane to bring up extra information about the row in the Extended Detail area.

Figure 1-3 Collecting information with the Time Profiler trace template