A number of instruments come built into the Instruments application. Each instrument has its own configuration options and way of displaying information, appropriate to the type of data that instrument collects. The built-in instruments are grouped into a handful of categories, based on the type of information that the instrument gathers. The following sections describe the built-in instruments in greater detail.
The following instruments gather data related to events in Core Data applications. You can use the information returned by these instruments to assess the performance implications of various events and to identify potential courses of action to correct issues.
The Core Data Saves instrument records save operations in Core Data applications. This instrument can operate on a single process or on all processes currently running on the system. It records data only for those processes that use Core Data. This instrument uses DTrace in its implementation and can be exported to a DTrace script.
This instrument captures the following information:
Caller. The name of the method that initiated the save operation (including the stack trace information.)
Save duration. The duration of the save operation in microseconds.
The Track pane can be set to display any of the following data:
Stack depth. The depth of the call stack.
Thread ID. The thread identifier.
Save duration. The duration of the save operation.
For each event in the Detail pane, you can open the Extended Detail pane to see the stack trace for that call, as well as the time at which the event occurred.
The Core Data Fetches instrument records data store fetch operations in Core Data applications. This instrument can operate on a single process or on all processes currently running on the system. It records data only for those processes that use Core Data. This instrument uses DTrace in its implementation and can be exported to a DTrace script.
This instrument captures the following information:
Caller. The name of the method that initiated the fetch operation (including the stack trace information).
Fetch entity. The name of the entity that was fetched.
Fetch count. The fetch count for that entity.
Fetch duration. The duration of the fetch operation in microseconds.
The Track pane can be set to display any of the following data:
Stack depth. The depth of the call stack.
Thread ID. The thread identifier.
Fetch count. The fetch count for that entity.
Fetch duration. The duration of the fetch operation.
For entries in the Detail pane, you can open the Extended Detail pane to see the stack trace for that call, as well as the time at which the event occurred.
The Core Data Faults instrument records fault events that occur during the lazy initialization of an NSManagedObject or its to-many relationship. This instrument can operate on a single process or on all processes currently running on the system. It records data only for those processes that use Core Data. This instrument uses DTrace in its implementation and can be exported to a DTrace script.
This instrument captures the following information:
Caller. The name of the method that triggered the fault (including the stack trace information).
Fault object. The name of the object that caused the fault.
Fault duration. The execution duration for the fault handler (specified in microseconds).
Relationship fault source.
Relationship. The relationship name.
Relationship fault duration. The relationship fault duration (specified in microseconds).
The Track pane can be set to display any of the following data:
Stack depth. The depth of the call stack.
Thread ID. The thread identifier.
Fault duration
Relationship fault duration
For entries in the Detail pane, you can open the Extended Detail pane to see the stack trace for that call, as well as the time at which the event occurred.
The Core Data Cache Misses instrument records fault events that result in cache misses. This instrument can operate on a single process or on all processes currently running on the system. It records data only for those processes that use Core Data. This instrument uses DTrace in its implementation and can be exported to a DTrace script.
Note: This instrument provides a subset of the behavior offered by the Core Data Faults instrument but is more useful for analyzing your application’s overall performance.
This instrument captures the following information:
Caller. The name of the method that triggered the cache miss (including the stack trace information).
Cache Miss. The name of the object that caused the cache miss.
CM duration. The execution duration for the fault handler (specified in microseconds).
RCM source. The relationship cache miss source.
RCM relationship. The relationship name.
RCM duration. The relationship cache miss duration (specified in microseconds).
The Track pane can be set to display any of the following data:
Stack depth. The depth of the call stack.
Thread ID. The thread identifier.
CM duration. See above.
RCM duration. See above.
For entries in the Detail pane, you can open the Extended Detail pane to see the stack trace for that call, as well as the time at which the event occurred.
The instrument in this section gathers data related to Grand Central Dispatch (GCD). GCD is a technology for executing asynchronous tasks concurrently. GCD is available in Mac OS X v10.6 and later and is not available in iOS.
You need to be familiar with GCD queues and block objects in order to use the Dispatch instrument effectively. For more information, see Concurrency Programming Guide.
The Dispatch instrument captures information about GCD queues created by your application and about the block objects that have been executing on these queues. It shows you the behavior of your application in terms of how your queues and block objects are executing. It records queue lifetimes, and tracks block invocations and their duration.
Dispatch helps you fine-tune the execution of your blocks. It shows you which blocks have been executing the most number of times and how long they have taken to execute on the CPU. You can find hot spots in terms of the blocks you’re enqueuing and optimize your code for those blocks. You can also find cases where you have queues in which blocks are executing synchronously. (GCD queues work more efficiently when work is performed asynchronously.)
Dispatch operates on a single process. This instrument uses DTrace in its implementation, but Dispatch trace data cannot be exported to a DTrace script.
For entries in the Detail pane, you can open the Extended Detail pane to see the stack trace for that call, as well as the time at which the event occurred.
Dispatch provides several different views of the trace data. The primary views are the queues view, the call tree view, and the blocks view. The call tree view is the default view. You can use buttons located below the Detail pane to display any of the three primary views.
The queues view shows you all the queues the application has created, the blocks that have been executed on them, and related statistics.
The queues view displays the following information:
Graph. If this option is selected, the Dispatch instrument plots statistics from this queue in the Track pane.
Queue Name. The name assigned by the user when the queue is created. The global queue names are assigned by the system.
Conc. Indicates that this queue is concurrent (rather than serial).
Live. Indicates that this queue is active (has not been freed yet).
# Blocks. Number of blocks currently enqueued but not invoked.
# Sync. Number of blocks that have been dispatched synchronously.
Total Processed. Total number of blocks executed.
Latency. Average time in milliseconds that blocks are on a queue. In other words, the average difference between invoke time and enqueue time.
Total CPU Time. Total time in milliseconds that the specified queue’s blocks have been executing on the CPU.
You can choose to display data from one or more queues in the Track pane. The Track pane can be set to display any of the following data:
Blocks Processed. Total number of blocks processed during a specified time period. The default period is 10 milliseconds.
Block Count. Number of blocks currently on a queue during a specified time period.
CPU Usage. Queue CPU activity during a specified time period.
Work Time. Total CPU time that a queue’s blocks consumed during the specified time period.
Latency. Average block latency in milliseconds during a specified time period.
For each queue listed in the queues view, you can click its focus button to see a list of the blocks that have been enqueued and invoked using the queue. This view is useful if you care about the execution order of your blocks or you want a more detailed view of the stack traces. You can select a block and display the extended detail view to see the enqueue and invoke stack traces for the block.
The call tree view aggregates all stack traces and displays them as call trees. If you separate the call trees by queue, you can see which queues have had the most activity, in terms of number of blocks invoked.
The call tree view displays the following information:
% Calls. Percent of total calls in which this stack trace has appeared.
# Calls. Number of times this stack trace has appeared.
Library. The name of the framework or bundle in which this stack trace appears.
Symbol Name. The frame identifier of the stack trace.
The Track pane can be set to display any of the following data:
Blocks Invoked. Number of blocks of specified type invoked during the specified time period.
Total Work Time. Total CPU time that blocks consumed during the specified time period.
For each symbol in the call tree view, you can click its focus button to prune the rest of the tree and focus on that particular node and its children. You can select a block and display the extended detail view to see the heaviest stack trace for the block.
The blocks view displays block and queue information. This view shows all blocks executed in a queue context, including blocks that were not explicitly enqueued. For example, if block A is enqueued and executes block B, both blocks are listed in the blocks view but only block A is listed in the queues view.
The blocks view displays the following information:
Graph. If this option is selected, the instrument plots statistics from this block in the Track pane.
Block Name. The name assigned to this block by the compiler.
Block Library. The framework or bundle in which the block has been declared.
Total Work Time. Total execution time for all invocations of this block in microseconds.
Average Work Time. Average execution time for this block in microseconds.
Count. Number of invocations of this block.
The extended detail view for a block shows you the maximum invoked stack trace. The block has been mostly invoked from this stack trace.
You can choose to display data from one or more blocks in the Track pane. The Track pane can be set to display any of the following data:
Blocks Invoked. Number of blocks of specified type invoked during the specified time period.
Total Work Time. Total CPU time that blocks consumed during the specified time period.
For each block in the blocks view, you can click its focus button to see a list of queues used to execute the block. For each queue, you can click its focus button to see a list of blocks associated with the queue. This view is useful if you care about which blocks were invoked in the queue context and their order of execution.
The instruments in this section provide diagnostics regarding energy usage in iOS devices. They also measure the on-off state of major device components.
iOS devices behave differently when operating on battery power versus external power. This could affect the data seen in these instruments. The Energy Usage instrument, in particular, will be affected. It’s not effective to measure Energy Usage while the device is connected to external power.
Here’s a typical workflow to use these instruments:
Connect the device to your development system.
Launch Xcode or Instruments.
On the device, Open Settings > Developer and turn on power logging.
Disconnect the device and perform the desired tests.
Reconnect the device.
In Instruments, open the Energy Diagnostics template.
Choose File > Import Energy Diagnostics from Device.
Energy diagnostics data is cleared when:
You turn off power logging on the device.
You disconnect the device and reboot.
You drain the battery.
The Energy Usage instrument measures energy usage since start-up. The instrument provides a macro measurement of a substantial workflow. The numeric scale is useful for comparison of different runs. Power source events (flags) are added programmatically.
The detail view displays the following information:
Energy Usage Level. Relative energy usage on a scale of 0-20.
Power Source Events. Transitions to battery or external power.
Note: The Energy Usage instrument is currently supported in the iPhone 3GS and the third-generation iPod touch.
The CPU Activity instrument gives an indication of what the device is doing. The instrument provides a condensed version of the Activity Monitor instrumentation.
The detail view displays the following information:
Time. The time interval for the measurement.
Total Activity. Percentage CPU activity.
Foreground App Activity. Percentage foreground app activity.
Audio Processing. Percentage audio activity.
Graphics. Percentage graphics activity.
App Activity. Application state transitions.
The Display Brightness instrument records changes in brightness that affect energy usage. The instrument does not record brightness changes due to ambient light sensor.
You can set the default screen brightness by choosing Settings > Brightness. When the screen turns on, the recording jumps to the preset level. When the screen turns off, the recording drops to zero.
The Sleep/Wake instrument displays a red band if the device is running and darker bands if the device is sleeping, attempting to sleep, or waking from sleep. During sleep, power measurement goes to zero. This instrument is useful in correlation with other instruments.
The Bluetooth instrument displays a red band if Bluetooth is active, or a black band if Bluetooth is off.
The WiFi instrument displays a red band if WiFi is active, or a black band if WiFi is off.
The GPS instrument displays a red band if GPS is active, or a black band if GPS is off.
The instruments in this section analyze file-system information and activity, such as read and write operations, permissions, and so forth.
The I/O Activity instrument records I/O events: calls to functions such as read, write, open, and close that operate on files. You can use this instrument to launch and sample a single process running on an iOS device. The I/O Activity instrument is analogous to the fs_usage utility in Mac OS X, although I/O Activity also provides backtraces with a full call tree view.
In the Detail pane, you can choose one or more of the following categories. Each category contains a set of probes (BSD functions):
File Attributes
File Permissions
Open and Close
Other
Read and Write
Shared Memory
Sockets
Stats
The I/O Activity instrument captures the following information:
Function. The name of the function being called.
Duration. The duration of the function call in microseconds.
In File. The input file descriptor.
In Bytes. The requested number of bytes to read or write.
Out File. The output file descriptor.
Out Bytes. The actual number of bytes read or written.
Thread ID. The thread identifier.
Stack Depth. The number of stack frames in use during this function call.
Error. The most recent error during the function call.
Path. The path to the file on which the executable performed the operation.
Parameters. Function call parameters. For a full description of the parameters for a specific function, see the API documentation.
The Track pane can be set to display any of the following data:
Sample number
Call duration
Input file descriptor
Input bytes
Output file descriptor
Output bytes
Thread ID
Stack depth
For any function call, you can open the Extended Detail pane to see the full backtrace for that call. The instrument also provides a full call tree view in the Detail pane.
The I/O Activity instrument is sometimes used in tandem with other iOS instruments. For example, you can use I/O Activity with the OpenGL ES instrument to examine the texture-loading process.
The File Locks instrument records advisory file-locking operations that use the flock function call. This instrument can operate on a single process or on all processes currently running on the system. This instrument uses DTrace in its implementation and can be exported to a DTrace script.
This instrument captures the following information:
The name of the function
The caller of the function (including the executable name and stack trace information)
The path to the file being locked
The operation type, which is an integer value corresponding to one of the following values (or a combination of values):
1 - shared lock
2 - exclusive lock
4 - don’t block when locking
8 - unlock
The Track pane can be set to display any of the following data:
Stack depth
Thread ID
Timestamp
For entries in the Detail pane, you can open the Extended Detail pane to see the stack trace for that call, as well as any available probe information and the time at which the event occurred.
The File Attributes instrument records changes to ownership and access permissions for files in the file system. This instrument can operate on a single process or on all processes currently running on the system. This instrument uses DTrace in its implementation and can be exported to a DTrace script. This instrument captures information about calls to each of the following functions:
Changes to file permission bits of a file made by the chmod and fchmod functions
Changes to the file owner and group of a file made by the chown and fchown functions
For each function call, this instrument captures the following information:
The name of the function
The caller of the function (including the executable name and stack trace information)
The path to the file on which the executable performed the operation
The file descriptor of the file that was modified
The mode flags, which indicate the permissions being applied to the file (This value is captured only for calls to chmod of fchmod.)
The user ID of the new file owner (This value is captured only for calls to chown of fchown.)
The group ID of the new group (This value is captured only for calls to chown of fchown.)
Note: For information about how to interpret the mode flags, see the chmod man page.
The Track pane can be set to display any of the following data:
Stack depth
Thread ID
File descriptor
Mode
User ID
Group ID
For entries in the Detail pane, you can open the Extended Detail pane to see the stack trace for that call, as well as any available probe information and the time at which the event occurred.
The File Activity instrument lets you monitor file system access. This instrument can operate on a single process or on all processes currently running on the system. This instrument uses DTrace in its implementation and can be exported to a DTrace script. This instrument captures information about calls to each of the following functions:
Open or create a file for reading or writing (open)
Delete a descriptor from the per-process reference table(close)
Get information about a file (fstat)
For each function call, this instrument captures the following information:
The name of the function
The caller of the function (including the executable name and stack trace information)
The path to the file on which the executable performed the operation
The file descriptor of the file
The Track pane can be set to display any of the following data:
Stack depth
Thread ID
File descriptor
For entries in the Detail pane, you can open the Extended Detail pane to see the stack trace for that call, as well as any available probe information and the time at which the event occurred.
The Directory I/O instrument records directory operations, such as moving directories, creating symbolic links, and so forth. This instrument can operate on a single process or on all processes currently running on the system. This instrument uses DTrace in its implementation and can be exported to a DTrace script. This instrument captures information about calls to each of the following functions:
delete - delete files and directories
link - create a hard or symbolic link
mkdir - create a directory
mount - mount a file system
rename - change the name of a file or directory
rmdir - remove a directory
symlink - create a symbolic link
unlink - remove a link
unmount - dismount a file system
For each function call, this instrument captures the following information:
The name of the function
The caller of the function (including the executable name and stack trace information)
The path to the file or directory on which the executable performed the operation
The new file or directory name (where appropriate)
The Track pane can be set to display any of the following data:
Stack depth
Thread ID
For entries in the Detail pane, you can open the Extended Detail pane to see the stack trace for that call, as well as any available probe information and the time at which the event occurred.
The instruments in this section collect information on memory reclaimed by the garbage collector. To use these instruments, the program must be built for garbage collection and must be run with garbage collection enabled. See Garbage Collection Programming Guide for information about writing and building a program for garbage collection.
The GC Total instrument tracks the total number of objects and bytes allocated and reclaimed by the garbage collector. This instrument can operate on a single process or on all processes currently running on the system. This instrument uses DTrace in its implementation and can be exported to a DTrace script. It records data only for those processes that have garbage collection enabled.
This instrument captures the following information:
The function that initiated the reclamation of objects (including the stack trace information)
The number of objects reclaimed by the garbage collector
The total number of bytes reclaimed by the garbage collector
The total number of allocated bytes still in use
The total number of bytes, both reclaimed and in use
The Track pane can be set to display any of the following data:
Stack depth
Thread ID
Objects reclaimed
Bytes reclaimed
Bytes in use
Total bytes
For entries in the Detail pane, you can open the Extended Detail pane to see the stack trace for that call, as well as any available probe information and the time at which the event occurred.
The Garbage Collection instrument measures the reclaim data of the Garbage Collector’s scavenge phase. This instrument can operate on a single process or on all processes currently running on the system. This instrument uses DTrace in its implementation and can be exported to a DTrace script. It records data only for those processes that have garbage collection enabled.
This instrument captures the following information:
The function that initiated the reclamation of objects (including the stack trace information)
The zone in which the memory is allocated
Whether the event is generational (1 for yes, 0 for no)
The number of objects reclaimed by the garbage collector
The number of bytes reclaimed by the garbage collector
The duration of the scavenge event (specified in microseconds)
The Track pane can be set to display any of the following data:
Stack depth
Thread ID
Zone
Is generational (the generational collector finds older objects no longer in use that are missed by the non-generational collector, but takes longer to run and is therefore run less frequently)
Objects reclaimed
Bytes reclaimed
Duration
For entries in the Detail pane, you can open the Extended Detail pane to see the stack trace for that call, as well as any available probe information and the time at which the event occurred.
The following instruments gather graphics-related data.
The Core Animation instrument measures the number of Core Animation frames per second in a process running on an iOS device. Offscreen frames are counted as well.
In addition, the Core Animation instrument can provide visual hints that help you understand how content is rendered on the screen. The instrument has a number of options that allow you to select specific types of rendering hints. The hints work in any application running on the device. It is not necessary to record samples to activate the hints. The hints are turned off when you close the Instruments document or delete the instrument. If there is an OpenGL surface being displayed, the rendering hints have no effect on the surface.
The instrument includes the following rendering hints:
Color Blended Layers. Puts a red overlay over layers that were drawn with blending enabled. Puts a green overlay over layers drawn without blending.
Color Copied Images. Puts a cyan overlay over images that were copied by Core Animation.
Color Immediately. Don't wait 10 ms after performing a color-flush operation.
Color Misaligned Images. Puts a magenta overlay over images whose source pixels aren't aligned to destination pixels.
Color Offscreen-Rendered Yellow. Puts a yellow overlay over offscreen-rendered content.
Color OpenGL Fast Path Blue. Puts a blue overlay over content that's detached from the compositor.
Flash Updated Regions. Flashes updated screen regions yellow.
You can use these rendering hints to find out if you’re doing unnecessary drawing—that is, redrawing content that hasn’t changed.
The Track pane displays the frames per second. The Extended Detail pane shows the statistics at each sample point.
The OpenGL Driver instrument samples OpenGL statistics. This instrument can operate on a single process or on all processes currently running on the system.
This instrument captures the following information:
Buffer swap count
Client GLWait time
Command2 DBytes per sample
Context2 DCount
Context GLCount
Free Context Buffer2 DWait time
Gart size bytes
Surface count
Texture count
Vram free bytes
and much more...
To see the full list of captured data, install the instrument and open the Extended Detail pane.
The Track pane indicates when the data was gathered. The Extended Detail pane shows the statistics at each sample point.
The OpenGL ES instrument queries the GPU driver on an iOS device to sample OpenGL statistics for a single process. The instrument helps you determine how efficiently you’re using OpenGL and the GPU on the device.
Note: Apple has shipped various GPUs, each with a different set of statistics. Instruments is unaware of what statistics will be displayed until it queries the device.
The GPU hardware effectively has two components: a tiler and a renderer. A scene is tiled and then rendered. The tiler and renderer components are often working on different scenes. The utilization of each component may reach 100%.
Tiler and renderer utilization can be useful for determining bottlenecks. A low renderer utilization might mean the process is stuck waiting for tiling, in which case decreasing scene complexity might help. Low tiler and renderer utilization can imply a CPU bottleneck elsewhere in a program.
This instrument captures the following information:
Context Count. The number of global OpenGL contexts. Note that there are other processes running (for example, SpringBoard) that can be responsible for creating a context. This statistic is useful for keeping an eye on any errant contexts that didn't get destroyed.
Command Buffer Allocated Bytes. The number of bytes allocated to store and submit command buffer data. This space is used to submit all OpenGL commands and vertex data specified by the user.
Command Buffer Submitted Bytes. The number of command buffer bytes submitted to the driver. The number includes all OpenGL commands and vertex data specified by the user. Submitted Bytes is incremented for every submission, by the total amount of memory used in that submission. You may want to divide by the Submit Count value to get an idea of average per-submission usage (this average should be slightly less than Allocated Bytes, because the allocated size is bound to what is actually being used.)
Command Buffer Submit Count. Incremented when a command buffer is pushed to the GPU (each of which may contain 0 or more scenes).
Command Buffer Implicit Submit Count. Incremented whenever a command buffer submission happens early—for example, when running out of command buffer space.
Renderer Utilization %. The percentage of the renderer that is currently being used.
Tiler Utilization %. The percentage of the tiler that is currently being used.
Device Utilization %. Records any device activity. The hardware is considered used if either the tiler or renderer, or anything else, is active.
Tiled Scene Bytes. The number of bytes used for tiling a scene. A high value indicates high scene complexity. If your scene is too complex to fit into the tiled scene bytes, you go into split scene mode, something that you should avoid. This statistic is incremented for every scene. To be useful, you need to divide the byte count by the number of scenes.
Split Scene Count. The number of times a component had to go into split scene mode. Split scene mode occurs when scene complexity is high and can't fit into the tiled scene bytes buffer. Split Scene Count and Tiled Scene Bytes can be used to determine the rendering paths in which you need to reduce complexity. A split scene is something that you should avoid.
Resource Bytes. The number of bytes used for textures.
Resource Count. The number of textures in use.
Scene Count. The number of times a scene was sent to be tiled and rendered. A scene is sent to be tiled and rendered when it is flushed or command buffer space is filled.
Implicit Scene Count. The number of times a scene was implicitly sent because OpenGL had reason to do so based on a particular state change. The count does not include explicit flushes by the user.
The Track pane indicates when the data was gathered.
Because events are not being captured, there is no backtrace in the Extended Detail pane. Instead, the Extended Detail pane shows the full list of statistics at each sample point.
OpenGL ES Analyzer is an iOS instrument that measures and analyzes OpenGL ES activity in an application. The instrument includes an expert system that finds problems and offers relevant solutions based on best practices and intricate knowledge of Apple's hardware and software platforms. The instrument also provides a large range of performance statistics.
Every time an application makes a call into the OpenGL ES framework, the instrument traces the call and records timing, duration, backtrace, and other parameters, and uploads this information to the host. The instrument analyzes this stream of OpenGL commands to compute useful performance statistics and to drive the expert system, that in turn offers correctness and performance suggestions.
For example, the instrument might tell you that it “detected vertex data array without using vertex buffer objects.” Vertex arrays are client data stored in main memory. It’s more efficient to upload this data to the GPU in the form of a vertex buffer object. Although the implementation is a little more complicated, the performance gains can be significant.
The instrument provides the following views:
Frame statistics. Corresponds to the timeline on the graph. Gives you the data being rendered in the graph in table form.
Analysis findings. Expert system recommendations, and a stack trace in the extended detail view. Color is used to indicate the severity of the problem. You can drill down to view specific occurrences of each category of recommendations, then drill down further to view which sequence of OpenGL ES commands generated that recommendation.
Function trace. Entire list of OpenGL commands, with arguments and the backtrace in extended detail view.
API statistics. Lists unique OpenGL calls with total time and average time for each call.
Call tree. Provides navigation of all OpenGL ES or EAGL functions called by the user, leveraging Instrument's data mining tools.
When you double-click a symbol in the backtrace from the analysis findings or the function trace, the relevant line of source code is displayed.
The Overrides section is used to bypass stages in the graphics pipeline. This allows you to isolate problems and find bottlenecks in your code.
Note: The OpenGL ES Analyzer instrument is currently supported in the iPhone 3GS and the third-generation iPod touch.
The following instruments gather data related to I/O operations.
The Reads/Writes instrument records reads from and writes to files. This instrument can operate on a single process or on all processes currently running on the system. This instrument uses DTrace in its implementation and can be exported to a DTrace script. It gathers information about each call to read and write functions, including read, write, pread, and pwrite.
This instrument captures the following information:
The name of the function
The caller of the function (including the executable name and stack trace information)
The path to the file on which the executable performed the operation
The file descriptor of the file that was modified
The number of bytes read or written
The Track pane can be set to display any of the following data:
Stack depth
Thread ID
File descriptor
Bytes
For any of these calls, you can open the Extended Detail pane to see the stack trace for that call, as well as any available probe information and the time at which the event occurred.
The Master Tracks section contains the User Interface recorder, which lets you record and play back a series of user actions in an application.
The User Interface instrument can launch an application or attach to a process and record your interaction with the user interface. You can then play back this recording as many times as you want, and run any other instruments you choose as you do so. You can use this instrument to create repeatable tests of the user interface as part of your quality assurance program and to capture errors that occur only sporadically. The use of the User Interface instrument is described in detail in “Working with a User Interface Track.”
The instruments in this section track memory use.
The Shared Memory instrument records the opening and unlinking of shared memory. This instrument can operate on a single process or on all processes currently running on the system. This instrument uses DTrace in its implementation and can be exported to a DTrace script. It gathers information about each shared memory access, including shm_open and shm_unlink.
This instrument captures the following information:
The name of the function
The caller of the function (including the executable name and stack trace information)
The name of the shared memory region
The flags used to open the shared memory region (see the shm_open man page)
The mode flags, indicating the access permissions for the region (see the chmod man page)
The Track pane can be set to display any of the following data:
Stack depth
Thread ID
Flags
mode_t
For any of these calls, you can open the Extended Detail pane to see the stack trace for that call, as well as any available probe information and the time at which the event occurred.
The ObjectAlloc instrument tracks memory allocation for an application. This instrument requires that you launch a single process so that it can gather data from the start of the process.
This instrument captures the following information:
Category - typically a Core Foundation object, an Objective-C class, or a raw block of memory.
Net Bytes - the number of bytes of this type currently allocated but not yet released.
# Net - the number of objects or memory blocks of this type currently allocated but not yet released.
Overall Bytes - the total number of bytes of this type that have been allocated, including those that have been released.
# Overall - the total number of objects or memory blocks of this type that have been allocated, including those that have been released.
# Allocations (Net / Overall) - A histogram of the current and total counts. The bars are normally shades of blue. They are colored shades of yellow when the ratio between the total number of objects and the peak, or the ratio between the peak and the current number, is 1/3 or less. The bars are shades of red when the ratio is 1/10 or less.
Although the ratios displayed aren't necessarily bad (often, they're normal over the long run of an application), Instruments colors them to point out allocation patterns that may deserve a further look. If you see categories where the color is red or yellow, you might try to eliminate unnecessary temporary allocations of the given type in your application. Similarly, you might simply try to eliminate the high-water mark in the number of objects.
The data table in the details pane contains a Graph column, which contains a checkbox for each row in the table. When the checkbox for a given category is enabled, the instrument displays the graph for that particular category type in the Track pane. Instruments automatically assigns a color to each graphed category.
When you mouse over category names in the details pane, a more Info button appears next to the category name. Clicking this button displays detailed information about the objects in that category, including the following attributes:
The address of the block.
The function call or class that generated the allocation event. For example, you can see which method in a class retained an object.
The creation time of the object.
The library responsible for creating the object.
For any of these events, you can open the Extended Detail pane to see the stack trace for each object allocation, including the type of allocation and the time at which the event occurred.
For specific instances of an object (or memory block), you can click the more info button in the Object Address column to see the allocation events associated with that object. For each allocation event, this instrument displays the following information:
The category of the object (its type)
The event type.
The timestamp for each event.
The address of the block
The size of the block
The library responsible for allocating the block.
The function that caused the allocation event.
For any allocation event, you can open the Extended Detail pane to see the stack trace, as well as any available event information and the time at which the event occurred.
To further filter information in the Detail pane, you can configure the Allocation Lifespan options. These options let you filter the allocation events based on the following criteria:
All Objects Created - display all objects, regardless of whether they have been deallocated.
Created & Still Living - display only objects that existed in memory when you stopped recording data..
The inspector for the ObjectAlloc instrument lets you configure the way the instrument tracks information. From the inspector, you can set the following options:
Record reference counts. Use this option to track the reference count of each object.
Discard unrecorded data on stop. Use this option to discard any data that has been gathered but not yet processed by the ObjectAlloc instrument.
For additional information about the ObjectAlloc instrument, see “Analyzing Data with the ObjectAlloc Instrument.”
The Leaks instrument examines a process’s heap for leaked memory. You can use this instrument together with the ObjectAlloc instrument to get memory address histories. This instrument requires that you launch a single process so that it can gather data from the start of the process.
This instrument captures the following information:
The number of leaks
The size of each leak
Address of the leaked block
Type of the leaked object
Each view mode in the Detail pane shows the leak data in a slightly different way. In table mode, this instrument shows the individual leaks along with the percentage that each individual leak contributes to the total amount of leaked memory discovered. In outline mode, the data is reorganized so that you can see how much memory is leaked from within a given symbol. For entries in either mode, the Extended Detail pane displays a heavy stack trace showing from where the leak originated.
For additional information about the Leaks instrument, see “Looking for Memory Leaks.”
The instruments in this section gather data about system activity and resources.
The Time Profiler instrument stops a Mac OS X program at prescribed intervals and records the stack trace information for each of the program’s threads. You can use this information to determine where execution time is being spent in your program and improve your code to reduce running time. Unlike many instruments, Time Profiler does not require DTrace probes in order to function. Time Profiler operates on a single process or all processes.
During sampling, this instrument captures the following information:
The time at which sampling began
The sampling duration
Stack trace information (including the library and caller information)
The maximum stack depth encountered during sampling
The function encountered most frequently during sampling (the hot frame)
Time Profiler lets you view this information in different ways. In table mode, you can view the samples in the order they were gathered, which shows the execution order of your code. In outline mode, Time Profiler provides a tree view of your program’s call stack and shows the number of samples that occurred in each function in that call stack.
To display a detailed call stack for a function, you can disclose items in the outline mode or select a function and open the Extended Detail pane. In outline mode, you can expand the entire call stack below a given entry by pressing the Option key and clicking the disclosure triangle for the entry.
The Track pane displays the stack depth at each sample time by default. This view is useful for identifying patterns of what is going on in your code. Because it is unlikely that two different execution paths will result in the same pattern of stack depths, when you see repeated structures in the graph, it is likely that the same code is being executed repetitively.
A unique feature of Time Profiler is the ability to record a profile without actually running Instruments. This feature is useful if you need to record a transient event and it would take too long to open and configure Instruments. To record a profile in this manner, first make sure Instruments is not running. Press the Instruments icon in the Dock. The Dock displays a menu that contains Time Profiler commands, settings, and profiles. You can choose to profile a specific process, all processes, or automatically profile any blocked (spinning) process. After a profile is created, it is listed under the Recent Time Profiles heading in the Instruments Dock menu. If you choose a profile, Instruments opens and displays the profile data.
The Time Profiler instrument and the Sampler instrument are similar, but there are some differences:
Time Profiler gathers backtrace data in the same manner as Shark, from kernel space. Sampler, on the other hand, gathers data from user space. Consequently, Time Profiler is more efficient than Sampler at gathering data.
Time Profiler can gather data from one or all processes. Sampler can only sample a single process.
Time Profiler can sample all thread states or running threads only. Sampler always samples all thread states. Generally, you’re interested in running threads. When your application is hung, you want to examine all thread states.
The Spin Monitor instrument automatically samples any applications that become unresponsive on the system. An application becomes unresponsive when it does not retrieve events from the window server for 3 or more seconds. Applications that are unresponsive during this time may actually be doing useful work or they may be hung. You can use the sample information generated by this instrument to adjust your code so as to ensure your application keeps processing events in a timely manner. This instrument can operate on a single process or on all processes currently running on the system.
During sampling, this instrument captures the following information:
The time at which sampling began
The sampling duration
Stack trace information (including the library and caller information)
The maximum stack depth encountered during sampling
The function encountered most frequently during sampling (the hot frame)
Each view mode in the Detail pane shows the sample data in a slightly different way. Both table and outline mode start by showing you the sessions during which a given application was sampled. Each session corresponds to a period of time where the application was deemed unresponsive and you can expand a given session to see what the application was during this time. In table mode, the instrument shows data about the functions that occurred most often during sampling. In outline mode, the instrument shows the number of samples that were gathered during each session. You can also show the running time for the samples that were gathered using the Sample Perspective options.
The inspector for this instrument lets you set the sample rate at which to gather samples. By default, this instrument gathers a sample once every 10 milliseconds.
The Sampler instrument stops a program at prescribed intervals and records the stack trace information for each of the program’s threads. You can use this information to determine where execution time is being spent in your program and improve your code to reduce running time. Unlike many instruments, Sampler does not require DTrace probes in order to function. This instrument operates on a single process.
The Sampler instrument records the following types of data for each sample:
The function being executed
The stack trace for each of the program’s threads
The time the sample was taken
The Sampler instrument lets you view this information in different ways. In table mode, you can view the samples in the order they were gathered, which shows the execution order of your code. In outline mode, Sampler provides a tree view of your program’s call stack and shows the number of samples that occurred in each function in that call stack.
In studying the performance of a running program you should compare the impact of a function to the cost of executing that function. If your program spends a lot of time in a low-impact function, this instrument can show you that behavior. You can then use the sample data to find out why your program is spending its time there and who is calling the function, which can lead you to fixing your code so that the function is called less frequently.
To display a detailed call stack for a function, you can disclose items in the outline mode or select a function and open the Extended Detail pane. In outline mode, you can expand the entire call stack below a given entry by pressing the Option key and clicking the disclosure triangle for the entry.
The Track pane displays the stack depth at each sample time by default. This view is useful for identifying patterns of what is going on in your code. Because it is unlikely that two different execution paths will result in the same pattern of stack depths, when you see repeated structures in the graph, it is likely that the same code is being executed repetitively. If this code also takes a long time to execute, it is a good target for optimization.
For additional information about the Sampler instrument, see “Analyzing Data with the Sampler Instrument.”
The Process instrument records processes forked by another process. This instrument can operate on a single process or on all processes currently running on the system. This instrument uses DTrace in its implementation and can be exported to a DTrace script.
This instrument captures the following information:
Execute a process (execve)
Process exit (exit)
The Process instrument returns information about each call made to these functions, including:
The name of the function (execve or exit)
The caller of the function (including the executable name, path, and stack trace information)
The process ID
The exit status of the process
The Track pane can be set to display any of the following data:
Stack depth
Thread ID
Process ID
Exit status
For any of these calls, you can open the Extended Detail pane to see the stack trace for that call, as well as any available probe information and the time at which the event occurred.
The Network Activity Monitor instrument records network traffic through the computer. This instrument can operate on a single process or on all processes currently running on the system.
The Track pane is set to display the following network-related data by default, but you can configure it to display other types of data as well. By default, it displays the following information:
The number of bytes sent each second
The number of bytes received each second
The number of packets sent each second
The number of packets received each second
The Memory Monitor instrument records the amount of real and virtual memory used by processes. This instrument can operate on a single process or on all processes currently running on the system.
The Track pane is set to display the following memory-related data by default, but you can configure it to display other types of data as well. By default, it displays the following information:
The number of virtual memory page ins
The number of virtual memory page outs
The total amount of virtual memory space in use
The total amount of free physical memory
The total amount of used physical memory
The Disk Monitor instrument records disk read and write operations. This instrument can operate on a single process or on all processes currently running on the system.
The Track pane is set to display the following disk-related data by default, but you can configure it to display other types of data as well. By default, it displays the following information:
The number of bytes per second written to disk
The number of bytes per second read from disk
The number of write operations processed per second
The number of read operations processed per second
The CPU Monitor instrument records the load on the system. This instrument can operate on a single process or on all processes currently running on the system.
The Track pane is set to display the following load values by default, but you can configure it to display other types of data as well. By default, it displays the following information:
The amount of load generated by the system
The amount of load generated by the user
The total load on the system
The Activity Monitor instrument records the load on the system measured against the virtual memory size. This instrument can operate on a single process or on all processes currently running on the system.
The Track pane is set to display the following load values by default, but you can configure it to display other types of data as well. By default, it displays the following information:
The total amount of virtual memory space in use
The amount of load generated by the system
The amount of load generated by the user
The total load on the system
The following instruments gather thread-related data.
The Java Thread instrument records the initialization and destruction of Java threads. It displays:
The time each measurement was taken
Total threads
You can specify the colors to use when charting the running, waiting, and blocked threads.
The Automation instrument allows you to automate user interface tests of your iOS application. You write JavaScript tests that use the user interface automation API to simulate user interactions with your application. The instrument exercises the user interface elements of your application as it runs on a connected iOS-based device, logging the results for your analysis.
Note: For your protection, the instrument does not allow you to process any application that is not code-signed with your provisioning profile. This includes any copy that has been downloaded from the iTunes App Store.
You write your tests in JavaScript, using the user interface automation API to specify actions that should be performed in your application while it runs on a connected device. See UI Automation Reference Collection for API details.
The test script must be a valid executable JavaScript file accessible to the instrument on the host computer. You can create as many scripts as you like, but you can run only one at a time.
The API offers a #import directive that allows you to write smaller, reusable discrete test scripts. For example, if you were to define commonly used functions in a file named TestUtilities.js, you could make those functions available for use in your test script TestXYZ.js by including in that script the line
#import "<path-to-library-folder>/TestUtilities.js"
With minor variations, you launch the Automation instrument much the way you would any other built-in instrument. The following procedure steps through the process:
Launch the Instruments application.
Choose the Automation template to create a trace document. (Alternatively, you can find the Automation template in the UI Automation category of the template library.)
Click the center button in the Primary View controller to select the detail view.
In the Target menu, choose iPhone, then choose your application from the list of iOS applications.
To run the Automation instrument, follow these steps:
Click the Script disclosure triangle, if necessary, to display the contents of that pane.
Click Choose Script.
In the Open panel, locate the script file and open it.
Click the Record button in the Instruments toolbar. Script log entries begin to appear in the Detail pane.
Click any script log entry in the Detail pane to reveal more information for that entry in the Extended Detail pane.
Use the stop and start script control buttons to stop/pause and start/resume execution of your test sequence script.
To configure Automation to automatically start and stop your script under control of the Instruments Record button in the toolbar, select the Run on Record checkbox.
If your application crashes or goes to the background, your script is blocked until the application is frontmost again, at which time the script continues to run.
Note that you must explicitly stop recording. Completion or termination of your script does not turn off recording.
The following instruments gather data for application-level events.
The Cocoa Events instrument records events sent through the sendEvent: method of the NSApplication class. This is the main method for dispatching events to a Cocoa application. You can use this instrument to correlate application events with other application behavior, such as memory and CPU usage. This instrument operates on a single process. This instrument uses DTrace in its implementation and can be exported to a DTrace script.
This instrument captures the type of event that was sent (both as an NSEventType code and spelled out).
The Track pane can be set to display any of the following data:
Stack depth
Thread ID
The event kind
For any of these calls, you can open the Extended Detail pane to see the stack trace for that call, as well as the time at which the event occurred.
The Carbon Events instrument records events returned by the WaitNextEvent function in the Carbon Event Manager. You can use this instrument to correlate application events with other application behavior, such as memory and CPU usage. This instrument operates on a single process. This instrument uses DTrace in its implementation and can be exported to a DTrace script.
This instrument captures the type of event that was sent.
The Track pane can be set to display any of the following data:
Stack depth
Thread ID
The event kind
For any of these calls, you can open the Extended Detail pane to see the stack trace for that call, as well as the time at which the event occurred.
Last updated: 2010-07-09