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 article 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 usually 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. If Instruments cannot find the dSYM file, you can provide the location of the dSYM path manually. After you have provided the appropriate dSYM path, Instruments can map addresses to their associated symbols and line number information.
Choose File > Symbols.
Click the Executables tab in the Symbols dialog.
Select the executable (binary) or framework that is missing symbols.
Click the Locate button; the “Select dSYM or containing folder” dialog opens.
Select your symbol file or the containing folder.
Click Open in the “Select dSYM or containing folder” dialog.
You may need to manually locateg a dSYM file when you build on one machine and test 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.
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.
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.
Zooming In and Out
After data has been recorded, you can zoom in and out on the track pane to refine the detail presented.
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.
Set the start of the range.
Drag the playhead to the desired starting point in the track pane.
Click the leftmost button in the Inspection Range control.
Set the end of the range.
Drag the playhead to the desired endpoint in the track pane.
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.
Do one of the following:
Choose View > Detail.
Click the middle View button in 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. See Instruments User Reference for information on each individual instrument’s Detail pane display options.
To view an instrument’s data using one of these formats, choose the appropriate mode from the rightmost menu in the navigation bar. Which modes an instrument supports depends on the type of data gathered by that instrument.
You can use disclosure triangles in the appropriate 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 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.
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.
Toggles the order in which calls are listed in the stack trace.
Displays the source file that defines each symbol whose source you own.
Displays the name of the library containing each symbol.
Displays the number associated with each frame in the stack trace.
Displays an icon representing the file in which each symbol is defined.
Trace Call Duration
Creates a new Instruments instrument that traces the selected symbol and places that instrument in the Instruments pane.
Look up API Documentation
Opens the Xcode Documentation window and brings up documentation, if available, for the selected symbol.
Copy Selected Frames
Copies the stack trace information for the selected frames to the pasteboard so that you can paste it into other apps.
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.
Click on a line in the Detail pane.
Double-click the symbol name in the Extended Detail pane.
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.