Touring Instruments

Instruments provides you with numerous ways to collect and examine information about your app. Instruments consists of two work areas, the trace template selection window and the trace document window. The trace template selection window, which appears when Instruments is first started, allows you to select a group of instruments based on their function. After you select a trace template, the trace document window appears. From this window, you can add more instruments, collect data, examine collected data, and much more. This chapter describes these sections and provides a quick walkthrough for each one.

Your First View: The Trace Template Selection Window

When Instruments opens, you are presented with a list of trace templates and platforms that are supported by Instruments on your machine. If you do not have the iOS SDKs installed, then you will not see the iOS platform displayed in the left column.

Figure 2-1  The Instruments window on opening

The opening screen is divided into three sections: platform, trace template, and trace template descriptions. Table Table 2-1 describes what is found in each of these sections.

Table 2-1  Opening screen sections

Feature

Description

Platform

There are three possible platforms available for Instruments: iOS, iOS Simulator, and OS X. Each platform contains its own set of trace templates that are configured to run on that platform. Certain instruments can run on any platform, but many are platform specific. You will see only those platforms you have downloaded the SDK for.

Trace template

Trace templates are groups of instruments that have been collected together in order to achieve a specific task. The trace templates shown change as you select the platform and group type.

Trace template description

The trace template description section provides a brief overview of what the type information that can be collected by the instruments contained within the trace template.

Collecting and Analyzing Data: The Trace Document Window

A trace document is a self-contained space for collecting and analyzing trace data. You use the document to organize and configure the instruments needed to collect data, and you use the document to view the data you’ve gathered, at both a high and low level.

Figure 2-2 shows a typical trace document. Because a trace document window presents a lot of information, it has to be well organized. As you work with trace documents, information generally flows from left to right. The farther right you are in the document window, the more detailed the information becomes.

Figure 2-2  The Instruments window while tracing
The Instruments window while tracingThe Instruments window while tracing

Table 2-2 lists some of the key features that are called out in Figure 2-2 and provides a more in-depth discussion of how you use that feature.

Table 2-2  Trace document key features

Feature

Description

Instruments pane

This pane holds the instruments you want to run. You can drag instruments into this pane or delete them. You can click the inspector button in an instrument to configure its data display and gathering parameters.

Track pane

The track pane displays a graphical summary of the data returned by the current instruments. Each instrument has its own “track,” which provides a chart of the data collected by that instrument. Although this pane’s information is read-only, it is in this pane that you select data points for closer examination.

Detail pane

The Detail pane shows the details of the data collected by each instrument. Typically, this pane displays the explicit set of “events” that were gathered and used to create the graphical view in the track pane. If the current instrument allows you to customize the way detailed data is displayed, those options are also listed in this pane.

Extended Detail pane

The Extended Detail pane shows even more detailed information about the item currently selected in the Detail pane. Most commonly, this pane displays the complete stack trace, timestamp, and other instrument-specific data gathered for the given event.

Navigation bar

The navigation bar shows you where you are and how you got there. It includes two menus, the active instrument menu and the detail view menu. You can click entries in the navigation bar to select the active instrument and the level and type of information in the detail view.

The trace document’s toolbar lets you add and control instruments, open views, and configure the track pane. Figure 2-3 identifies the different controls on the toolbar, and Table 2-3 provides detailed information about how you use those controls.

Figure 2-3  The Instruments toolbar
The Instruments toolbarThe Instruments toolbar
Table 2-3  Trace document toolbar controls

Control

Description

Pause/Resume button

Pauses the gathering of data during a recording. This button does not actually stop recording, it simply stops Instruments from gathering data while a recording is under way. In the track pane, pauses show up as a gap in the trace data.

Record/Stop button

Starts and stops the recording process. Use this button to begin gathering trace data.

Loop button

Sets whether the user interface recorder should loop during play back to repeat the recorded steps continuously. Use this setting to gather multiple runs of a given set of steps.

Target menu

Selects the target for the document. The target is the process (or processes) for which data is gathered.

Inspection Range control

Selects a time range in the track pane. When set, Instruments displays only data collected within the specified time period. Use the buttons of this control to set the start and end points of the inspection range and to clear the inspection range.

Time/Run control

Shows the elapsed time of the current trace. If your trace document has multiple data runs associated with it, you can use the arrow controls to choose the run whose data you want to display in the track pane.

View control

Hides or shows the Instruments pane, Detail pane, and Extended Detail pane. This control makes it easier to focus on the area of interest.

Library button

Hides or shows the instrument library. For information on using the Library window, see “Adding and Configuring Instruments.”

Search field

Filters information in the Detail pane based on a search term that you provide. Use the search field’s menu to select search options.