Collecting Data on Your App
For Instruments to help you monitor and improve your app, it has to be able to collect information on your app while it is running. This chapter describes how to direct Instruments to collect information on your app.
Setting Up Data Collection with the Target Pop-up Menu
The target pop-up menu in the toolbar is used to set both the device and the app or process on which you will be collecting data. Click on the target pop-up menu to make your choice.
The Target pop-up menu provides you with the following main choices for collecting data:
All Processes. Collects data from all processes currently running on the system.
Choose Target. Collects data from a specific app that you specify. The app automatically launches when you click the Record button.
Typically, users collect data from one app at a time. When you target a single app, all of the instruments in the trace document collect data from the targeted app.
Select Choose Target from the target pop-up menu.
Locate your app and press the Choose button.
The target pop-up menu also provides quick access to select certain processes to target without opening the choose target window. For iOS development, this including apps you’ve installed, running apps, and system processes. For OS X development, it includes recently profiled apps, running apps, and system processes.
When selecting a platform in the target pop-up menu, you only see iOS devices when they are plugged into your computer or when you have configured Instruments to collect data from a particular device wirelessly.
Make sure your mobile device is connected to your development system by a USB cable.
Press the Option key and click the target pop-up menu in the toolbar of your trace document.
Choose your mobile device to enable the wireless option.
Open the target pop-up menu and choose the wireless version of your device.
Disconnect the device from the USB cable.
Using a wireless connection allows you to move your device as needed for testing without getting tangled in the cable or accidentally unplugging the device during testing. Connecting wirelessly is especially useful when testing the following:
Accelerometers. Move the device in all directions without its being tethered. Connecting wirelessly ensures a complete testing of the device.
Accessories. Plug your USB accessory into the free slot and test it.
Collecting Data from the Dock
Save time by running Time Profiler from the Instruments app icon in the Dock to automatically record certain events in the background, even without Instruments running. Using this method, you can perform the following tasks:
System Time Profile. Starts profiling all system processes.
Time Profile Specific Process. Starts the Time Profiler instrument with a specific app from the pop-up menu.
Automatically Time Profile Spinning Applications. Automatically profiles blocked (spinning) apps in the future.
Allow Tracing of Any Process (10 hours). Trace any process that occurs in the next 10 hours. Bypasses having to type in a password during the 10 hours.
Collecting Data Using iprofiler
iprofiler is a command-line tool used to measure an app’s performance without launching Instruments. After collecting the performance data, import the data to Instruments in order to get a visual representation of the data. The collected data is saved in a
.dtps bundle that can be opened by Instruments.
iprofiler supports the following trace templates:
Activity Monitor. Monitors overall system activity and statistics, including cpu, memory, disk, and network. Activity Monitor also monitors all existing processes and parent/child process hierarchies.
Allocations. Measures heap memory usage by tracking allocations, including specific object allocations by class. Allocations can also record virtual memory statistics by region.
Counters. Collect performance monitor counter events using time or event based sampling methods.
Event Profiler. Samples the processes running on the system’s CPUs through low-overhead, event-based sampling.
Leaks. Measures general memory usage, checks for leaked memory, and provides statistics on object allocations by class as well as memory address histories for all active allocations and leaked blocks.
System Trace. Provides comprehensive information about system behavior by showing when threads are scheduled, and showing all their transitions from user into system code through either system calls or memory operations.
Time Profiler. Performs low-overhead, time-based sampling of processes running on the system’s CPUs.
iprofilercommand to collect data.
Open Instruments and click File > Open.
Find the saved
.dtpsfile and click Open.
After importing the saved file, Instruments automatically opens the associated instruments in a trace document and populates them with the collected data. You can view and manipulate this data to locate any issues with your app.
iprofiler provides a limited set of configuration options for defining what data to collect.
Provides a list of all supported instruments.
Provides a list of all supported instruments and a description of what each template does.
Executes the legacy Instruments command-line interface found in
Sets the length of time that data is collected for. If this option is not set, then data is collected for 10 seconds. Duration can be set to seconds (1s or 1), milliseconds (10m or 10ms), or microseconds (10u or 10us).
Sets the frequency with which a measurement is taken during the sample time. If this option is not specified, it uses the Instruments default interval time. The interval can be set to seconds (1s or 1), milliseconds (10m or 10ms), or microseconds (10u or 10us).
Limits the performance measurement to the final period of the
Note: This option can be used only with the -
Specifies the destination path and the name used when saving the collected data. If the path is not specified, the output is saved to the current working directory. If the basename is not specified, the process name or process ID is used.
Designates the instrument that is to be run. Valid name options are -
At least one template must be listed. You can run up to all seven templates at once.
Backtraces only include kernel stacks when this option is used.
Backtraces include both kernel and user stacks.
Use this flag with -counters to specify the mnemonic of the event to count. Multiple mnemonics should be comma-separated.
Causes the Time Profiler template to profile all threads. If this is not specified, then Time Profiler profiles only running threads.
Attaches to a process that is already running. Specifying a string will attach the process whose name starts with that string. Specifying a process ID attaches it to the process associated with that process ID.
Causes the target process to be launched for the duration of the measurement. Lists the executable and the arguments as if they are being invoked from the command-line.
A list of common
iprofiler command-line examples are below.
The following example collects data from all running processes for the current sampling duration set in Instruments using the Time Profiler and Activity Monitor instruments. The collected data is saved to the working directory as
iprofiler -timeprofiler -activitymonitor
The following example opens and collects data from YourApp using the Time Profiler instrument. Data is collected for eight seconds and the data is saved at
iprofiler -T 8s -d /temp -o YourApp_perf -timeprofiler -a YourApp
The following example collects data from the process with the 823 process ID using the leaks and activity monitor instruments. Data is collected for 2500 milliseconds (2.5 seconds) and saves it to the working directory as
iprofiler -T 2500ms -o YourApp_perf -leaks -activitymonitor -a 823
The following example opens and collects data from YourApp using the Time Profiler and Allocations instruments. Data is collected for the default amount of time set in Instruments and saved in
iprofiler -d /tmp -timeprofiler -allocations -a YourApp.app
The following example opens and collects data from YourApp found in
/path/to with the argument
arg1 using the Time Profiler and System Trace instruments. Data is collected for fifteen seconds, but only the data collected in the last 2 seconds is saved. The data is saved to the working directory as
iprofiler -T 15 -I 1000ms -window 2s -o YourApp_perf -timeprofiler -systemtrace /path/to/Your.app arg1
Minimizing Instruments Impact on Data Collection
Instruments is designed to minimize its own impact on data collection. By changing some basic settings, you can further decrease the impact Instruments has on data collection.
You can decrease the sample interval for many instruments in order to collect more data. However, high sample rates that result from a short sample interval can cause several problems:
Processor time is required for every sample. High sample rates use more processor time.
Sample interval timing may not be consistent. Interrupts are used to start each sample. Variables in when these interrupts occur can cause significant variations in the sample rate when using very small sample intervals.
Small sample intervals cause more samples to be taken. Each sample uses system memory and a large number of samples quickly uses up the available memory on smaller memory machines.
You can change the sample interval for an instrument by opening the Record Settings inspector for that instrument.
Running Instruments in Deferred Mode
Increase the accuracy of performance-related data by deferring data analysis until you quit the app you are testing. Typically, Instruments analyzes and displays data while your app runs, allowing you to view the data as it is collected. Performing analysis live slows down the target process by taking up CPU time and memory, which leaves you with measurements that may not reflect how the process would normally behave. Running Instruments in deferred mode delays the analysis of data until the data collection is done, either after your app has finished running or after you click Stop. While in deferred mode, you are blocked from interacting with the instruments that are collecting data.
In deferred mode, after Instruments has finished collecting data, Instruments processes the data and displays it onscreen. Even though deferring the data analysis adds time to the later stages of the data collection process, it helps ensure that performance-related data is accurate.
You can set Instruments to run in deferred mode in the Instruments preferences.
Choose Instruments > Preferences.
In the General tab, select the “Always use deferred mode” checkbox.
Using deferred mode moves the data processing to after the collection of data, resulting in a delay at the end of data collection as Instruments processes the data. In the event of especially long traces, this delay can be significant. To avoid this delay, you can set deferred mode for only those traces that require extremely precise data collection.