Instruments Help Articles

About the Instruments Trace Document

The Instruments trace document is used to collect and analyze data, based on a specific configuration of settings. The trace document consists of five primary areas:

Toolbar: Contains the basic controls for recording data and controlling how the trace document is displayed.

Instruments pane: Lists the individual instruments currently active in the trace document. If the CPUs or Threads strategy is selected in the toolbar, then this pane lists the CPUs or threads analyzed.

Track pane: Displays a graphical summary of the data collected over time.

Toolbar: The trace document’s toolbar lets you add instruments, open and close views, start, pause, and stop recording of data, and configure certain attributes of the trace document. It contains the following areas:

Record: These two buttons allow you to record, pause, and stop data collection.

Record/Stop button: Starts and stops the recording process. Use this button to begin gathering trace data, and to stop when you’re done.

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.

Target: Your choice in this pop-up menu designates the target for data collection, by device and by app.The target is the process (or processes) for which data is gathered.

Time/Run: This activity viewer shows the elapsed time of the current trace or the position of the inspection head in the track pane. If your trace document has multiple data runs associated with it, that is shown here.

Library: The Add button (+) shows or hides the instruments library, allowing you to add new individual instruments to your trace document. The library contains a complete list of available instruments. For information on using the Library window, see Adding a New Instrument to an Existing Trace Document.

Strategy: These three buttons control the type of information displayed in the Instruments pane.

CPU: Displays a list of CPU cores in the instruments pane, and their collected data in the track pane. Only available when a trace document contains instruments that record CPU data.

Instruments: Displays a list of instruments in the instruments pane, and their corresponding data in the track pane.

Threads: Displays a list of treads in the instruments pane, and their corresponding data in the track pane. Only available when a trace document contains instruments that record thread data.

View: These buttons hide or show display of the detail and inspector sidebar panes.

Instruments pane: This pane holds the instruments your trace document uses to collect data, lined up with a data collection track in the track pane. You can drag instruments into this pane from the Library (+), select and delete them, and configure them in the inspector sidebar.

This pane can also display a list of CPU cores and threads, if your trace document contains instruments that record these kinds of data. You can toggle the type of information displayed in this pane by clicking the strategy buttons in the toolbar.

The track pane zoom control slider at the bottom of this pane allows you to adjust the scale of the data displayed in the track pane.

Track pane: The track pane displays a graphical summary of the data returned for the current trace run.

Each instrument, CPU core, or thread has its own “track,” which provides a graphical chart of the data collected. Although this pane’s information is read-only, you can select specific data points here for closer examination. Each track is lined up with its corresponding instrument, CPU core, or thread in the Instruments pane. You can change how graphical information is displayed here by changing instrument configuration settings in the inspector sidebar or by adjusting the zoom level in the Instruments pane.

Detail pane: This pane shows specific information about the data collected by each instrument. Select an instrument in the instrument pane to display an explicit set of “events” that were gathered and used to create the graphical view in the track pane.

The navigation bar at the top of the detail pane displays a quick view of how you got to your current location in the data view. It includes at least two menus, the active instrument menu and the detail view menu, and some instruments like Allocations allow you to drill deeper. You can click entries in the navigation bar to select the active instrument and the level and type of information in the detail view.

Active instrument menu: Allows you to select which instrument’s information is displayed in the display pane.

Detail view menu: Allows you to select the type of information to display in the display pane. This varies depending on the selected instrument.

The search field to the right of the navigation bar allows you to filter collected data for a specific term. Click the search field’s menu for some additional filtering options. You can also filter more extensively by adjusting display settings in the inspector sidebar.

Inspector sidebar: This pane is used to adjust instrument settings, detail display options, and to provide additional information about specific instruments.

The inspector control bar includes options for what is displayed in the inspector sidebar. Buttons include:

Record Settings button: Allows you to adjust configuration settings for the currently selected instrument in the instruments pane.

Display Settings button: Allows you to adjust options for filtering the information displayed in the detail pane.

Extended Detail button: Displays additional detail information, such as the complete stack trace, timestamp, and other instrument-specific data gathered for a selected event in the detail pane.