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 Navigation bar is used to set both the device to collect data on and the app or process you will be collecting data on. Click on the Target pop-up menu to make your choice.
The Target pop-up menu provides you with three choices for collecting data:
All Processes. Collects data from all processes currently running on the system.
Attach to Process. Collects data from a currently running process of your choice.
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.
Click Choose Target from the Target pop-up menu.
Click Choose Target to search for an app
Previously targeted apps are shown below the Choose Target option.
Select your app and press the Choose button.
You can set each instrument in a trace document to collect data from a particular app, process, or device, independent of the other instruments. In this way, you can collect data on how multiple apps interact with each other.
Choose Instrument Specific from the Target pop-up menu.
Click the instrument’s inspector icon.
Choose the targeted app or process from the pop-up menu in the Target section.
You can add multiple versions of the same instrument to your trace document by dragging another copy of the instrument from the Library into the document to record data from a different app, process, or device with each version of the instrument.
You can collect various streams of data simultaneously. For example, you could simultaneously collect data from:
All processes with one instrument.
A single app with a second instrument
A different app with a second version of the second instrument
A third app with a third instrument
For iOS development, the pop-up menu for the target selection includes only the targets you can profile. For OS X development, the pop-up menu includes the targets you have already profiled.
When selecting the platform, you see iOS devices only 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 by a USB cable.
Press the Option key and click the Target pop-up menu.
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 record events while Instruments is not running. Record fleeting or transient events. You can profile the following:
System Time Profile. Starts profiling all system processes.
Time Profile Specific Process. Starts the Time Profiler instrument with the targeted 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 via 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 trace templates and populates them with the collected data. You can view and manipulate the 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 templates.
Provides a list of all supported templates 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 template 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.
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 templates. 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 template. 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 templates. 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 templates. 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 templates. 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 clicking the inspector icon for that instrument.
Running Instruments in Deferred Mode
Increase the accuracy of performance-related data by deferring data analysis until you quit the application you are testing. Instruments analyzes and displays data while your app runs, allowing you to view the data as it is collected. Running Instruments in deferred mode delays the analysis of data until the data collection is done, either after your application 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 back end 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.
© 2013 Apple Inc. All Rights Reserved. (Last updated: 2013-04-23)