Examining Your Collected Data

After collecting information about your app, you need to examine what you collected. Even though every instrument is different, they have several things in common. This chapter describes common tasks that are used to help you examine the information you have collected.

Locating Symbols for Your Data

Instruments requires accurate information about your project in order to provide you with the best results. You will get the most complete information if the system can see all of the symbols associated with your project. When addresses, rather than symbols, are displayed in trace documents generated by the Instruments analysis tool, you can manually provide the missing information. The mapping of addresses to their symbols is contained in a dSYM file. Typically, Instruments finds dSYM files automatically, based on the locations that Spotlight indexes and the paths you specify in Instruments Preferences. However, you can point Instruments in the right direction when it can’t automatically find a dSYM. Once you do, Instruments can map addresses to their associated symbols and line number information.

To locate the dSYM path for a trace document
  1. Choose File > Symbols.

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

  2. Select the executable (binary) or framework that is missing symbols.

  3. Click the Locate button; the “Select dSYM or containing folder” dialog opens.

  4. Select your symbol file or the containing folder.

  5. Click Open.

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. Therefore, you may need to manually locate a dSYM file when you build on one machine and test performance on another.

The filter bar in the Symbols dialog lets you filter by binary/framework or missing information, or you can search for a binary/framework by entering text into the search field.

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 easy 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 Leaks instrument can also point out places where your app is not handling memory properly. If the graph for Leaks is relatively empty, you know that your app is behaving properly, but if the graph is not empty, you might want to examine why that is. Figure 5-1 shows an example of the track pane after collecting data.

Figure 5-1  An example of graphical data in the track pane of a trace document

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 methods give you the ability to display collected 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 at the current playhead position 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 expand or contract the detail presented. Dragging your mouse cursor across a section of data allows you to zoom in or out when done with either the Shift or Control keys pressed. The zoom slider also controls the level of zoom in the track pane.

To zoom in and out of your data

Do one of the following:

  • To zoom in, press the Shift key, and drag across the section of data you wish to isolate. Alternately, you can drag the zoom slider to the right.

  • To zoom out, press the Control key, and drag across a section of data. Alternately, drag the zoom slider to the left.

  • Drag the track pane zoom slider at the bottom of the Instruments pane.

Viewing Data for a Specific Range of Time

Zooming in on a particular event in the track pane lets you see what happened around a specific time. You may also want to see only the data collected over a specific range of time.

You can set an inspection range by holding the mouse button down and dragging in the track pane of the desired instrument. If you drag across a section of data without using any modifier keys, you will select that data to be the only data displayed. 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.

You can also use the Inspection Range controls in the View menu to accurately select only the data collected in a specific time range.

To select a time range for inspection using the View menu
  1. Set the start of the range.

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

    2. Click View > Set Inspection Range Start.

  2. Set the end of the range.

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

    2. Click View > Set Inspection Range End.

Instruments highlights the contents of the track pane that fall within the range 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.

When you set a time range, Instruments filters the contents of the detail pane, showing data collected only within the specified range. You can use this method to very quickly narrow down a 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 outside the selected range or click View > Clear Inspection Range.

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-2 shows a section of the track pane highlighted before it is zoomed in on.

Figure 5-2  Zooming in on a section of data

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-3 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.

Figure 5-3  The detail pane
The Detail paneThe Detail pane
To open or close the Detail pane

Do one of the following:

  • Choose View > Detail.

  • Click the left View button at the right end of the toolbar.

Changing the Display Style of the Detail Pane

For some instruments, you can display the data in the detail pane using more than one format. For example, the Activity Monitor instrument allows you to view a summary of data, parent child information, and a list of samples. To view an instrument’s data using one of the available formats, choose the appropriate mode from the rightmost menu in the navigation bar at the top of the detail pane. Which modes an instrument supports depends on the type of data gathered by that instrument.

For some modes, like the Time Profiler’s call tree mode, you can use disclosure triangles in certain detail pane rows to dive further down into the corresponding hierarchy. Clicking a disclosure triangle expands or closes just the given row. To expand both the row and all of its children, hold down the Option key while clicking on a disclosure triangle.

Sorting in the Detail Pane

You can sort the information displayed in the detail pane according to the data in a particular column. To do so, click the appropriate column header. The columns in the detail pane differ with each instrument.

Working in the Extended Detail Inspector

For some instruments, the Extended Detail inspector shows additional information about the item currently selected in the detail pane. The Extended Detail inspector 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-4 shows the Extended Detail inspector 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.

Figure 5-4  Extended Detail inspector
Extended Detail paneExtended Detail pane
To open or close the Extended Detail inspector

Do one of the following:

  • Choose View > Inspectors > Show Extended Detail.

  • Press Command+2.

  • Click the Extended Detail button in the Inspector control at the top of the Inspector sidebar pane.

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 row in the detail pane.

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

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

You can hide system calls in a stack trace by clicking the button at the top of the stack trace area in the Extended Detail inspector, as seen in Figure 5-5.

Figure 5-5  The button for hiding system calls in a stack trace

For more information on accessing source code from Instruments and viewing stack traces, please refer to Accessing Source Code from Instruments and Viewing Stack Traces Related to Your Code.