Examining Your Collected Data

Resymbolicating Your Data

Instruments requires accurate information about your project in order to provide you with the best results. This is accomplished by ensuring that the system is able to see all of the symbols associated with your document. Resymbolicate your document when addresses, rather than symbols, are displayed in trace documents. Symbolication maps addresses to their associated symbols and line number information.

Resymbolication is often necessary when building on one machine and testing performance on another. To correctly display symbols in trace documents, Instruments needs access to the specific symbol files that were generated when the executable you are testing was built.

To resymbolicate your app

1. Choose File > Re-Symbolicate.

   This option appears only after running a trace or loading a previously saved trace.

2. In the Re-Symbolicate dialog that appears, click the Binaries tab.

3. Highlight the binary (executable) from which your trace document was made.

4. Press the Locate button.

5. Click Symbolicate.

   

Viewing the Collected Data in the Track Pane

The most prominent portion of a trace document window is the track pane. The track pane occupies the area immediately to the right of the instruments pane. This pane presents a high-level graphical view of the data gathered by each instrument. You use this pane to examine the data from each instrument and to select the areas you want to investigate further.

The graphical nature of the track pane makes it easier to spot trends and potential problem areas in your app. For example, a spike in a memory usage graph indicates a place where your app is allocating more memory than usual. This spike might be normal, or it might indicate that your code is creating more objects or memory buffers than you had anticipated in this location. An instrument such as the Spin Monitor instrument can also point out places where your app becomes unresponsive. If the graph for Spin Monitor is relatively empty, you know that your app is being responsive, but if the graph is not empty, you might want to examine why that is.

Figure 5-1 shows a sample trace document and calls out the basic features of the track pane. You use the timeline at the top of the pane to select the period you want to investigate. Clicking in the timeline moves the playhead (a position control showing a common point in time) to that location and displays a set of inspection flags that summarize the information for each instrument at that location. Clicking in the timeline also focuses the information in the Detail pane on the surrounding data points; see “Examining Data in the Detail Pane.”

Although each instrument is different, nearly all of them offer options for changing the way data in the track pane is displayed. In addition, many instruments can be configured to display multiple sets of data in their track pane. Both features give you the option to display the data in a way that makes sense for your app.

The sections that follow provide more information about the track pane and how you configure it.

Setting Flags

Flags allow you to quickly access points of interest in the track pane. You can add names and descriptions to flags in order to add information specific to that flag.

To set flags in the track pane

Do one of the following:

• Choose Edit > Add Flag.

• Press Command–Down Arrow.

Zooming In and Out

After data has been recorded, you can zoom in and out on the track pane to refine the detail presented.

To zoom in and out of your data

Do one of the following:

• Press the Shift key, and drag across a section of data to zoom in.

• Press the Control key, and drag across a section of data to zoom out.

Viewing Data for a Range of Time

Although zooming in on a particular event in the track pane lets you see what happened at a specific time, you may also be interested in seeing the data collected over a range of time. You use the Inspection Range control (shown in Figure 5-2) to focus on the data collected in a specific time range.

To mark a time range for inspection

1. Set the start of the range.

   1. Drag the playhead to the desired starting point in the track pane.

   2. Click the leftmost button in the Inspection Range control.

2. Set the end of the range.

   1. Drag the playhead to the desired endpoint in the track pane.

   2. Click the rightmost button in the Inspection Range control.

Instruments highlights the contents of the track pane that fall within the range that you specified. When you set the starting point for a range, Instruments automatically selects everything from the starting point to the end of the current trace run. If you set the endpoint first, Instruments selects everything from the beginning of the trace run to the specified endpoint.

You can also set an inspection range by holding the Option key and dragging in the track pane of the desired instrument. Dragging makes the instrument under the mouse the active instrument (if it is not already) and sets the range using the mouse-down and mouse-up points.

When you set a time range, Instruments filters the contents of the Detail pane, showing data collected only within the specified range. You can quickly narrow down the large amount of information collected by Instruments and see only the events that occurred over a certain period of time.

To clear an inspection range, click the Clear Range button in the center of the Inspection Range control.

Isolating a Segment of the Data Collection Graph

While pressing the Option key, drag across a section of the data collection graph to view the data in the selected range. As you drag the cursor, the start time and the duration of the time filter appear. The Detail pane changes to display only the information contained within the time filter. Figure 5-3 shows a section of the track pane highlighted before it is zoomed in on.

Examining Data in the Detail Pane

After you identify a potential problem area in the track pane, use the Detail pane to examine the data in that area. The Detail pane displays the data associated with the current trace run for the selected instrument. Instruments displays only one instrument at a time in the Detail pane, so you must select different instruments to see different sets of details.

Different instruments display different types of data in the Detail pane. Figure 5-4 shows the Detail pane associated with the File Activity instrument, which records information related to file system routines. The Detail pane in this case displays the function or method that called the file system routine, the file descriptor that was used, and the path to the file that was accessed. For information about what each instrument displays in the Detail pane, see Instruments User Reference.

To open or close the Detail pane

Do one of the following:

• Choose View > Detail.

• Click the middle View button in the toolbar.

Working in the Extended Detail Pane

For some instruments, the Extended Detail pane shows additional information about the item currently selected in the Detail pane. The Extended Detail pane usually includes a description of the probe or event that was recorded, a stack trace, and the time when the information was recorded. Not all instruments display this information, however. Some instruments may not provide any extended details, and others may provide other information in this pane.

Figure 5-5 shows the Extended Detail pane for the Allocations instrument. In this example, the instrument displays information about the type of memory that was allocated, including its type, pointer information, and size.

To open or close the Extended Detail pane

Do one of the following:

• Choose View > Extended Detail.

• Click the Extended Detail View button in the toolbar.

You can configure the information shown in the stack trace using the Action menu at the top of that section. Clicking and holding the Action menu icon displays a menu from which you can enable or disable the options in Table 5-1.

If you have an Xcode project with the source code for the symbols listed in a stack trace, you see the code in the Detail pane’s Console area. Instruments is able to display your code in the Detail pane and can even open Xcode so that you can make any desired changes.

To see your personal code

1. Click on a line in the Detail pane.

2. Double-click the symbol name in the Extended Detail pane.

   

3. Click the Xcode icon in the top right of the Detail pane to make changes.

   

You can collapse stack traces by using the slider control at the bottom of the Extended Detail pane. This control governs backtrace compression with filtering. Its purpose is to reduce the detail in the stack trace and to display only what matters.