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:

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.

bullet
To target a single app
  1. Click Choose Target from the Target pop-up menu.

  2. Click Choose Target to search for an app

    Previously targeted apps are shown below the Choose Target option.

  3. Select your app and press the Choose button.

    ../Art/chess_target.png

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.

bullet
To set different targets for multiple instruments
  1. Choose Instrument Specific from the Target pop-up menu.

  2. Click the instrument’s inspector icon.

  3. Choose the targeted app or process from the pop-up menu in the Target section.

    ../Art/Specify_target_for_instrument.png

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:

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.

bullet
To enable a wireless device
  1. Make sure your mobile device is connected by a USB cable.

  2. Press the Option key and click the Target pop-up menu.

  3. Choose your mobile device to enable the wireless option.

  4. Open the Target pop-up menu and choose the wireless version of your device.

  5. 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:

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:

bullet
To collect Time Profiler information from the Dock
  1. Control-click the Instruments dock icon.

  2. Choose the call stack to profile.

  3. Click All Thread States to profile all available threads.

  4. Choose the process to profile to start recording.

    ../Art/Instruments_from_dock.png

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:

bullet
To collect and view data from iprofiler
  1. Open Terminal.

  2. Enter an iprofiler command to collect data.

  3. Open Instruments and click File > Open.

  4. Find the saved .dtps file 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.

Figure 4-1  Imported Time Profiler data

iprofiler provides a limited set of configuration options for defining what data to collect.

Command

Description

-l

Provides a list of all supported templates.

-L

Provides a list of all supported templates and a description of what each template does.

-legacy

Executes the legacy Instruments command-line interface found in /usr/bin/instruments.

-T duration

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).

-I interval

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).

-window period

Limits the performance measurement to the final period of the iprofiler run. If this option is not specified, performance is measured throughout the entire run. The period can be set to seconds (1s or 1), milliseconds (10m or 10ms), or microseconds (10u or 10us).

Note: This option can be used only with the -timeprofiler and -systemtrace template options.

-d path -o basename

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.

-instrument name

Designates the template that is to be run. Valid name options are -activitymonitor, -allocations, -counters, -eventprofiler, -leaks, -systemtrace, and -timeprofiler.

At least one template must be listed. You can run up to all seven templates at once.

-kernelstacks

Backtraces only include kernel stacks when this option is used.

If neither -kernelstacks or -userandkernelstacks options are specified, backtraces include user stacks only.

-userandkernelstacks

Backtraces include both kernel and user stacks.

If neither -kernelstacks or -userandkernelstacks options are specified, backtraces include user stacks only.

-allthreadstates

Causes the Time Profiler template to profile all threads. If this is not specified, then Time Profiler profiles only running threads.

-a process/pid

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.

The -leaks option requires that a specific single process or process ID be specified.

executable [args…]

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.

iprofiler Examples

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 allprocs.dtps.

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 /temp/YourApp_perf.dtps.

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 YourApp_perf.dtps.

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 /tmp/allprocs.dtps.

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 YourApp_perf.dtps.

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:

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.

bullet
To set deferred mode for Instruments
  1. Choose Instruments > Preferences.

  2. In the General tab, select the “Always use deferred mode” checkbox.

    ../Art/Deferred_display_all.jpg

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.

bullet
To set deferred mode for a trace
  1. Choose File > Record Options.

  2. Select the “Deferred Mode” checkbox, then click OK.

    ../Art/Deferred_Mode_for_a_template.png