Guides and Sample Code

Developer

Instruments User Guide

On This Page

Preferences

Access the preferences window by choosing Instruments > Preferences from the menu bar, or pressing Command-Comma (,). This window contains options for customizing Instruments.

General Preferences

Use these settings to configure basic Instruments behavior such as startup options, keyboard shortcuts, and warning options (see Figure 73-1 and Table 73-1).

Figure 73-1General preferences in Instruments image: ../Art/instruments_prefs_general_2x.png
Table 73-1General preferences

Option

Description

Compress run data

Compresses each saved run into zip format.

Enforce initial deck height

Prevents custom deck height from being restored when an instrument document is reloaded and uses the template’s default deck height. When deselected, saves and restores the current deck height.

Sort process lists by identifier

Sorts all lists of apps in Instruments by process ID. When deselected, sorts apps alphabetically.

Always snap track to fit at end of run

Automatically scales the track in a trace document at the end of a run to fit all data in the window.

Reset “Don’t Ask Me” Warnings

Reenables dialog warnings you previously elected not to show. Instruments has several warning dialogs that you can disable by selecting the “Do not show this message again” checkbox in the dialog. To reenable all of these warning dialogs, click the Reset “Don’t Ask Me” Warnings button.

Recording Preferences

Use these settings to configure how tracks are displayed in your trace documents (see Figure 73-2 and Table 73-2).

Figure 73-2Recording preferences in Instruments image: ../Art/instruments_prefs_recording_2x.png
Table 73-2Recording preferences

Option

Description

Recording location

Specifies the location where new Instruments documents are created. By default, this is a temporary directory. From this pop-up menu, choose Custom to use a different directory.

Background sampling duration

Sets the length of a sample trace operating in the background. Type a numeric value in the field. Defaults to 5 seconds.

Global keyboard shortcuts

Opens the Keyboard > Shortcuts > Services pane in the System Preferences app, as shown in Figure 73-3. From here, you can assign keyboard shortcuts to development services, such as a service that automatically opens an Xcode project in Instruments and profiles it with the System Trace profiling template.

Always use deferred mode

Performs data analysis for all traces after data collection is complete.

Automatically time profile spinning applications

Automatically monitors for a spinning process while a trace is recorded. This can be a process other than the one being recorded. If detected, Instruments starts the Time Profiler instrument on the spinning process.

DTrace max buffer size

Sets the size of the DTrace kernel buffer (in megabytes). The default is 25 MB.

Dtrace max backtrace depth

Sets the maximum stack depth that is captured when using a DTrace instrument. The default is 128 frames.

Permit zero match probes

Prevents an error when a specified DTrace probe is not found.

Preserve intermediate files

Prevents Instruments from removing intermediate DTrace data output files from the disk.

Flag runtime messages

Adds flags to the timeline for DTrace runtime status and error messages encountered during a recording.

Figure 73-3The Keyboard > Shortcuts > Services pane in System Preferences image: ../Art/system_preferences_keyboard_shortcuts_services_2x.png

CPUs Preferences

Use these settings to configure Instruments for the CPU configuration of your device (see Figure 73-4 and Table 73-3).

Figure 73-4CPUs preferences in Instruments image: ../Art/instruments_prefs_cpus_2x.png
Table 73-3CPUs preferences

Option

Description

Active processor cores

Adjusts how many cores of your system are active. Only active cores are scheduled to perform any operations when profiling. Use the slider to set the number of active cores equal to the number of cores on the device that you expect your app to run on. Changes to this preference persist until you change it again or until your system is put to sleep or restarted.

Hardware Multi-Threading

Allows CPU cores to utilize multiple execution units. When disabled, there is only one active execution unit per processor core.

Symbols Preferences

Use these settings to configure global search paths for symbols in Instruments (see Figure 73-5 and Table 73-4).

Figure 73-5Symbols preferences in Instruments image: ../Art/instruments_prefs_symbols_2x.png
Table 73-4Symbols preferences

Option

Description

+

Adds a search location. Opens the Open Directory dialog. Click the Add button (+) to open the Open Directory dialog and then navigate to the desired directory and click Open. Directories indexed by Spotlight are already searched, so you only need to add search paths for directories that aren’t indexed.

-

Removes a selected search location. Select a path, and click the Delete button (-) to remove the path.

dSYM download script

Provides the option of running a user-provided script to copy remote dSYMs to the local machine. This dSYM download script must be written to accept a UUID argument, fetch the corresponding dSYM and executable locally, and print out a property list, whose format is described on the LLDB Debugger website.

This option is intended for use by developers whose dSYMs may reside on a remote build server; it is not needed by the majority of developers.

When a run ends

Enabled only if a dSYM download script is specified. Configures how the download script is automatically used after a recording has finished. Options include:

  • Don’t Download dSYMs (Default Option)

  • Download App dSYMs

  • Download App and User Framework dSYMs

  • Download All dSYMs