The User Interface instrument records the user interaction with your Mac application and lets you replay the recording. This instrument records every event that occurs when you run the application. Choose the UI Recorder template to use the User Interface instrument.

Before You Trace

User Interface recording requires the Enable access for assistive devices checkbox to be selected in the Universal Access section of Apple’s System Preferences. The System Preferences application should be in your Applications folder.

User Interface Instrument Results

When you finish a trace with the User Interface instrument, it shows the following information for each event:

• Sample number.
• A thumbnail image of where the event happened.
• Triggers, whose purpose escapes me. For me it always shows an image of a menu with Triggers as the menu choice.
• The type of event, such as mouse button down, mouse moved, and key down.
• Key, which tells you the key that was pressed for a keyboard event.
• Title, which is the title of the view where the event occurred: window, view, control, menu, etc. 
• Location, which tells you the location of the event. Mouse button events are the most common events to have a location.

Don’t worry if you see lots of samples with blank values in the Key, Title, and Location columns. That’s normal behavior. In the track pane mouse events are blue, keyboard events are green, and system events are yellow.

Replaying what the User Interface Instrument Recorded

To replay a sequence you recorded, you must first finish a trace by clicking the Stop button. The Record button now has the title Drive and Record. Click the Drive and Record button to replay the recording. Instruments creates a new run and replays the event sequence.

Researching Instruments for Xcode Tools Sensei allowed me to become familiar with most of the built-in instruments. Due to the high number of instruments, there was no way for me to cover them all in the book. I focused on the most commonly used instruments in the book. I can use this blog to explain some of the other instruments. I start with the OpenGL Driver instrument.

What the OpenGL Driver Instrument Does

The OpenGL Driver instrument records OpenGL statistics. Some statistics this instrument records include the following:

• The amount of free video memory.
• The number of textures used.
• The number of buffer swaps.
• The amount of time the CPU waited for the GPU.
• The number of surfaces the GPU allocated.

Obviously OpenGL applications are the ones to benefit from the OpenGL Driver instrument. The OpenGL ES Driver instrument records similar information for iOS applications. The OpenGL ES Driver instrument is available in both the OpenGL ES Driver and OpenGL ES Analysis templates. In most cases you should use the OpenGL ES Analysis template for OpenGL ES profiling.

One thing you’ll notice when you create a new trace document is there is no template for the OpenGL Driver instrument. Pick one of the other templates (Time Profiler and Empty would be good choices for profiling purposes) and add the OpenGL Driver instrument to the trace document by dragging the instrument from the Library to the instrument list. Click the Library button in the trace document window toolbar to open the Library.

Before You Trace

Before you start tracing you must tell Instruments the statistics to show in the track pane and detail view. Click the Info button next to the OpenGL Driver instrument to open a pop-up editor. Click the Configure button to see all the available statistics. Select the checkbox next to a statistic to tell Instruments to show it in the track pane and detail view. The extended detail view shows all the statistics so you should show only the most important statistics in the track pane and detail view.

The screenshot also shows where you set the sampling rate.

Trace Results

Use the Target menu in the trace document window toolbar to pick an application to profile. Click the Record button to start profiling. Click the Pause button to pause recording and see the statistics. The track pane graphs each statistic you told the OpenGL Driver instrument to observe.

The detail view at the bottom of the trace document window has one column for each statistic you told Instruments to show. There is one row in the detail view for each sample the OpenGL Driver instrument recorded. Selecting a sample from the list shows all the OpenGL statistics for that sample in the extended detail view. The extended detail view is on the right side of the trace document window. If you don’t see it, choose View > Extended Detail or click the right button in the View group in the toolbar.

Tags: xcode 4

I have seen several questions recently on Stack Overflow from people using the Allocations instrument in Instruments. When looking through the information the Allocations instrument provides, they have difficulty finding the areas of their code responsible for the memory allocations. Answering questions on this topic several times on Stack Overflow tells me it’s time to make a post about finding where your application allocates memory.

There are three views in Instruments that can help you find the parts of your code that are allocating large amounts of memory: the extended detail view, the call tree view, and the source view.

Extended Detail View

When you select a memory allocation from the detail view, the extended detail view shows the call stack for that memory allocation. Examining the call stack can help you find the function in your code that makes the memory allocation. To open the extended detail view, choose View > Extended Detail or click the right button in the View group in the toolbar.

Call Tree View

The Allocations instrument initially shows the table view, which tells you memory allocation statistics. Switching to the call tree view can help you find where your application allocates memory. Use the jump bar to switch to the call tree view.

To the left of the call tree view is the Call Tree collection of checkboxes. Selecting the Invert Call Tree and Hide System Libraries checkboxes can help you quickly find your code in the call tree view.

Source View

Double-clicking one of your functions from the extended detail view’s call stack or the call tree view opens the source view. The source view highlights the lines of code in the function that are allocating memory and tells you the amount of memory allocated. More information on the source view is available in the Instruments Source View post, but keep in mind that some parts of the post do not apply in Xcode 4.

Xcode 4.2 adds two instruments for Mac applications that users of the Shark performance tool will appreciate. The Event Profiler instrument records a sample when a low-level event occurs. The Counters instrument samples your application and collects PMC (Performance Monitor Counter) events. PMC events are low-level CPU events, such as incorrectly predicted branches and cache misses.

Before you trace with the Event Profiler and Counters instruments, you must first configure them. Click the Info button next to the instrument in the instrument list to open a pop-up editor. The pop-up editor is where you configure the instrument. You must tell the Event Profiler instrument the event that triggers sampling. Choose an event from the Event Name menu.

You must specify the PMC events to collect to use the Counters instrument. Click the + button to add an event to the Counters list. Choose an event from the pop-up cell.

When you choose PMC events to collect for the Counters instrument, Instruments shows only a subset of the available PMC events. Choose Window > Manage PM Events to control the PMC events the Counters instrument can collect.

Most of the PMC events are hidden initially. Choose Visible from the State pop-up cell to make that event visible. When you add an event for the Counters instrument to collect, the event you made visible should be one of the choices in the pop-up cell.

Tags: xcode 4

One of Instruments’ most powerful features is the ability to create your own instruments. Apple supplies an Objective-C provider to DTrace, which Instruments is built on. In the Objective-C provider, you can tell a probe to fire when you enter or exit an Objective-C method. Supplying the method name can be tricky, especially if the method takes multiple arguments. This post shows you how to supply a method name to an Objective-C custom instrument.

Create a new instrument in Instruments by choosing Instrument > Build New Instrument. If you choose the Objective-C provider, the top of the probe looks like the following:

As you can see in the screenshot, you can supply a class and a method name to limit when the probe fires. Suppose you want the probe to fire when you enter an Objective-C method. You would enter the following for a method that takes no arguments:

-MethodName  (Instance method)

+MethodName  (Class method)

If the method takes one argument, place a colon after the method name.

-MethodName:

Things become more complicated if the method takes multiple arguments. You can’t have multiple colons in the method name text field because DTrace interprets colons as provider field separators. Use question marks instead of colons to separate the method’s arguments. Let’s look at an example. Suppose you have the following Objective-C method in your application:

- (BOOL)readFromFileWrapper:(NSFileWrapper*)appFileWrapper ofType:(NSString*)typeName error:(NSError**)outError

You would enter the following as the method name:

-readFromFileWrapper?ofType?error?

Notice how you enter the argument name, which is the text to the left of the colon, and a question mark for each argument.

Cocoa’s NSZombie class helps you discover where you are accessing a deallocated object in your code. For those of you running Snow Leopard, Instruments has support for NSZombie so you can use NSZombie without having to make any changes to your Xcode project.

Checking for zombies is pretty simple. Open your project in Xcode. Choose Run > Run With Performance Tool > Zombies. Your application will launch and Instruments will trace its execution. If your application accesses a deallocated object, a zombie message appears in Instruments.

Clicking the focus button next to the memory address shows the history of that memory address. The Responsible Caller column tells you where you’re trying to access a deallocated object.

If the Run With Performance Tool option is grayed out in Xcode, launch Instruments (or choose File > New if Instruments is already running) and select the Zombies template. The Zombies template is available for Mac applications and iPhone applications running in the Simulator. Use the Target menu in the trace document window toolbar to choose your application. Click the Record button to start recording.

Instruments 2, which ships with Xcode 3.2, added a source view that lets you examine your source code inside Instruments. When you combine the source view with the extended detail view, finding the problem areas in your code becomes easier.

Switching to the Source View

At the bottom of the trace document window is a collection of six buttons.

If you see only four buttons, you’re most likely running Leopard and Instruments 1. Instruments 2 requires Snow Leopard. The buttons from left to right are:

• Table view
• Outline view
• Diagram view
• Console
• Source view
• Extended detail view

The source view looks similar to an Xcode editor window. Click the source view button to switch to the source view.

I’ll briefly explain the other views for those of you new to Instruments. The table, outline, and diagram views provide different views of the trace data. The table view shows the data in a flat list. The outline view shows the data in a hierarchical list, and the diagram view shows the data as a list of individual samples. Most instruments do not use the diagram view.

The console is similar to Xcode’s debugger console. If your application uses NSLog or printf to log debugging information, the logged output appears in the console when you trace the application in Instruments.

For most instruments the extended detail view shows the call stack. The extended detail view is initially invisible. To take full advantage of the source view, open the extended detail view. The extended detail view resides on the right side of the trace document window.

Viewing Source Code

When you first open the source view, it displays the following message:

Drop Source File to Analyze

Drag one of your source code files to the source view to examine it in the source view.

There is a second way to view source code. Make sure the extended detail view is open. Switch to the table, outline, or diagram view. Select a trace sample and examine the call stack in the extended detail view. Find a function you wrote on the call stack and double-click it. If there is no function you wrote on the call stack, select another trace sample.

When you double-click a function you wrote, something cool happens. Instruments switches to the source view and displays the function you double-clicked. It also highlights the code with a message bubble that looks similar to the message bubbles Xcode shows when you have a compiler error or warning. The exact contents depend on the instrument, but the following is an example from the ObjectAlloc instrument:

Each line of code that allocates memory is highlighted. The amount of memory allocated by that line of code appears on the right.

The Leaks instrument highlights every line of code that leaks memory and tells you the total amount of leaked memory. The Time Profile and Sampler instruments tell you the number of samples recorded for a line of code.

If you look at the screenshot, you’ll notice an information button next to the amount of allocated memory. Clicking the information button shows you the five heaviest backtraces. For the ObjectAlloc instrument, the heaviest backtraces are the largest memory allocations. For the Leaks instrument, the heaviest backtraces are the largest memory leaks.