---

Built-in Instruments

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.

In this section:

Core Data
File System
Garbage Collection
Graphics
Input/Output
Master Tracks
Memory
System
Threads/Locks
User Interface

Core Data

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.

Core Data Saves

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:

• The method that initiated the save operation (including the stack trace information)

• The duration of the save operation (specified in microseconds)

The Track pane can be set to display any of the following data:

• Stack depth

• Thread ID

• Save 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.

Core Data Fetches

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:

• The name of the entity that was fetched

• The caller of the function (including the stack trace information)

• The fetch count for that entity

• The duration of the fetch operation (specified in microseconds)

The Track pane can be set to display any of the following data:

• Stack depth

• Thread ID

• Fetch count

• Fetch 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.

Core Data Faults

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:

• The name of the object that caused the fault

• The name of the method that triggered the fault (including the stack trace information)

• The execution duration for the fault handler (specified in microseconds)

• The relationship fault source

• The relationship name

• The relationship fault duration (specified in microseconds)

The Track pane can be set to display any of the following data:

• Stack depth

• Thread ID

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

Core Data Cache Misses

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.

This instrument captures the following information:

• The name of the object that caused the cache miss

• The name of the method that triggered the cache miss (including the stack trace information)

• The execution duration for the fault handler (specified in microseconds)

• The relationship cache miss source

• The relationship name

• The relationship cache miss duration (specified in microseconds)

The Track pane can be set to display any of the following data:

• Stack depth

• Thread ID

• Cache miss duration

• Relationship cache miss 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.

File System

The instruments in this section analyze file system information and activity, such as read and write operations, permissions, and so forth.

File Locks

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.

File Attributes

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

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.

File Activity

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.

Directory I/O

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.

Garbage Collection

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.

GC Total

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.

Garbage Collection

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.

Graphics

The following instruments gather graphics-related data.

OpenGL Driver

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.

Input/Output

The following instruments gather data related to I/O operations.

Reads/Writes

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.

Master Tracks

The Master Tracks section contains the User Interface recorder, which lets you record and play back a series of user actions in an application.

User Interface

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

Memory

The instruments in this section track memory use.

Shared Memory

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.

ObjectAlloc

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

Leaks

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

System

The instruments in this section gather data about system activity and resources.

Spin Monitor

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.

Sampler

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

Process

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.

Network Activity Monitor

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

Memory Monitor

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

Disk Monitor

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

CPU Monitor

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

Activity Monitor

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

Threads/Locks

The following instruments gather thread-related data.

Java Thread

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.

User Interface

The following instruments gather data for application-level events.

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

Carbon Events

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.

---