Getting Around Instruments

Instruments has several key windows and dialogs.

Profiling Template Selection Dialog

When Instruments launches, you’re presented with a list of profiling templates—files containing sets of preconfigured instruments—from which to choose. This list includes a set of standard templates as well as any custom templates you may have created. (See Figure 5-1.)

Figure 5-1The profiling template selection dialog

The profiling template selection dialog consists of the following primary elements:

• Target device list: Click this to select the device on which you wish to profile.

• Target process list: Click this to select the process or processes to profile.

• Filter buttons: Click these to filter down the list of templates to display just the standard templates, custom templates, or recently used templates.

• Search field: Enter some text to quickly find the template you need. This searches template titles and descriptions.

• Template list: The list of profiling templates, which may be filtered if you clicked a filter button or entered search criteria.

• Template description: A short description of the currently selected profiling template, which can be helpful for determining whether the selected template meets your needs.

• Choose button: Click this to create a new profile document, based on the currently selected template.

  This button changes to Profile when you press the Option key. Click the Profile button to create a new document based on the currently selected template and immediately begin profiling the target process.

• Open button: Click this to open a previously saved profile document, rather than starting with a fresh template.

• Cancel button: Click this to close the template selection dialog.

Trace Document

A trace document (Figure 5-2) is used to organize and configure instruments for profiling, initiate data collection, and view and analyze the results. You create a new trace document by launching Instruments and choosing a profiling template or by initiating profiling from Xcode, the Dock, or the command line. You can also save and reopen trace documents in which you’ve configured instruments and collected data. A trace document can contain a lot of extremely detailed information, and this information is presented to you through a number of panes and areas.

Figure 5-2The trace document

Toolbar

The toolbar (Figure 5-3) allows you to start, pause, and stop data profiling, add instruments, hide and show panes, and more.

Figure 5-3The trace document toolbar

It includes the following main elements:

• Profiling controls: Allow you to record, pause, and stop data collection.

• Target device list: Allows you to select the device on which you wish to profile.

• Target process list: Allows you to select the process or processes to profile.

• Activity viewer: Shows the elapsed time of the current trace or the position of the inspection head in the timeline pane. If your trace document has multiple data runs associated with it, that’s shown here too.

• Add Instrument button (+): Shows or hides the instruments Library palette, which contains a complete list of available instruments. From here, you can select individual instruments and add them to your trace document.

• Strategy buttons: Control the type of information displayed in the timeline pane.

  • CPU (): Displays a list of CPU cores, along with their collected data, in the timeline pane. Only available when a trace document contains instruments that record CPU data.

  • Instruments (): Displays a list of instruments and their corresponding data in the timeline pane. 

  • Threads (): Displays a list of threads and their corresponding data in the timeline pane. Only available when a trace document contains instruments that record thread data.

• View buttons (): Hide or show the detail pane and inspector.

Timeline Pane

The timeline pane displays a graphical summary of the data recorded for a given trace. In this pane, each instrument, CPU core, or thread has its own “track,” which provides a graphical chart of the data collected. Click the strategy buttons in the toolbar to display instrument, CPU core, or thread data.

Although this pane’s information is read-only, you can scroll through data, select specific areas for closer examination, and insert flags to highlight points of interest. You can change how graphical information is displayed here by adjusting the zoom level or by changing the record settings of individual instruments in the inspector.

Instruments strategy view

This is a list of all the individual instruments contained within your trace document, along with their collected data (see Figure 5-4). You can drag new instruments to the list from the Library palette (see Add an Instrument to a Trace Document). If you select an instrument in the list, you can delete it or configure it in the inspector pane. The instruments list is visible by default when you create a trace document.

Figure 5-4Instrument activity in the trace document timeline pane

CPU strategy view

If your trace document contains instruments that record CPU-related data, a list of CPU cores and their usage over time is displayed here (Figure 5-5).

Figure 5-5CPU activity in the trace document timeline pane

Threads strategy view

If your trace document contains instruments that record thread-related data, a list of threads and their utilization is displayed here (Figure 5-6).

Figure 5-6Thread activity in the trace document timeline pane

Detail Pane

This pane shows detailed information about the data collected by the instruments in your trace document (see Figure 5-7). Select an individual instrument in the timeline pane to see the data it collected while profiling.

Figure 5-7The trace document detail pane

Navigation bar

The navigation bar at the top of the detail pane (Figure 5-8) helps you browse through collected data. You can use it to switch between types of data and to navigate through different levels of data.

Figure 5-8The navigation bar in the trace document detail pane

• Instrument: Icon of the currently selected instrument in the timeline pane. Click this to view the console for the instrument.

• Detail type list: Allows you to navigate between different types of data. The options displayed here vary, depending on the actively selected instrument. For many instruments, the list includes things like a summary of data, a call tree, and a console. 

• Detail tree: Keep track of where you are in the hierarchy as you navigate through the data in the detail pane. Click a branch of the tree to move back up the hierarchy to the corresponding data. 

• Filter field: Allows you to filter collected data for a specific term. Click the filter field’s menu for some additional filtering options. You can also filter collected data more extensively by adjusting display settings in the inspector pane.

Collected data area

The collected data area (Figure 5-9) shows you all of the data for the selected instrument, typically in tabular format. The content displayed here varies significantly from instrument to instrument. For example, the Activity Monitor instrument displays process, CPU, and thread information, and much more.

Figure 5-9The collected data area in the trace document detail pane

Often, individual symbols and data points within this area contain navigation buttons (), which appear when you move your pointer over them. You can click these buttons to move deeper into the data. As you do, the detail tree in the navigation bar updates to reflect where you are in the hierarchy, as shown in Figure 5-10.

Figure 5-10The trace document detail pane’s hierarchy navigation

Inspector Pane

This pane contains instrument-specific settings (Figure 5-11), which you can adjust in order to control recording behavior and the visible information in the timeline and detail panes. This pane also sometimes shows additional information that may be useful when browsing through data in the detail pane.

Figure 5-11The areas of the trace document inspector pane

Record settings area

The settings available in this area vary, depending on the active instrument. Often, instruments provide settings that allow you to adjust certain attributes pertaining to how data is recorded, such as the sample rate or the types of statistics to capture, as seen in Figure 5-12.

Figure 5-12The record settings area of the trace document inspector pane

Display settings area

The settings in this area also vary, depending on the instrument. These settings can help you:

• Control the data that appears in the detail pane. For example, an instrument may allow you to hide system libraries when navigating a call tree.

• Navigate recorded data more efficiently through filtering and data mining.

• Adjust how recorded information is represented in the timeline view. An instrument may, for example, allow you to change the style of graph used to represent its collected data.

Figure 5-13 shows an example of display settings for a selected instrument.

Figure 5-13The display settings area of the trace document inspector pane

Extended detail area

This area doesn’t contain any settings. Rather, it is used to display additional instrument-specific information about selected data in the detail pane, such as a complete stack trace, as shown in Figure 5-14.

Figure 5-14The extended detail area of the trace document inspector pane

Library Palette

The Library palette (Figure 5-15) provides a complete list of available instruments and allows you to add them to your trace documents. Here, you can browse instrument descriptions and filter for a specific instrument. To display the Library palette, choose Window > Library, press Command-L, or click the Add Instrument button (+) in the trace document toolbar.

Figure 5-15The Library palette

For more information, please see the following sections:

• Find Instruments in the Library Palette

• Add an Instrument to a Trace Document

Flags Palette

The Flags palette (Figure 5-16) displays a list of any flags you may have applied in the timeline pane of the active trace document. In this palette, you can select a flag to quickly navigate to it in the timeline. You can also filter through a large list of flags for a specific one, show and hide your flags, and view timestamp information about your flags.

Figure 5-16The Flags palette

Preferences Window

The preferences window (Figure 5-17) is used to control various settings related to the behavior of Instruments. Here, you can adjust general settings that pertain to startup, saving, and more. You can also adjust recording settings, CPU settings, and symbol preferences. See Preferences for a complete list of settings and options that may be modified through this window.

Figure 5-17The General preferences window

Getting Around Instruments