In previous posts, MarkD delved into many of the diagnostic tools available to us in Instruments, such as the Time Profiler and the Energy Diagnostics template. In that same vein, I’ll provide an overview of the Cocoa Layout Instrument.

To aid us in our discovery, I have provided a fairly simple project. It is an iPhone app that uses Auto Layout to lay out a UICollectionView and its UICollectionViewCells’ content. Download the sample project and accompanying trace output, and let’s get started.

The Cocoa Layout Instrument is available for use with the iOS simulator and Cocoa desktop apps. However, the instrument cannot be used with an iOS device. The Cocoa Layout Instrument provides a timeline of all events occurring in relation to instances of NSLayoutConstraint, much like a backtrace. Apple explains the tool in the documentation on Analysis Tools.

How Can I Fire This Instrument Up?

Start the Cocoa Layout Instrument by performing the following steps:

1. Open the sample project.
2. Select Product > Profile (⌘-I).
3. Select the Cocoa Layout template.
4. The Instruments window will appear in a paused state. Press the red Record button (⌘-R) in the top left.
5. Swipe through the images, then press the pause button to stop recording events.

For the remainder of this post, I will use the trace I provided so that the instructions will match the results. To follow along, open the file cocoa-layout-instrument.trace.

What Am I Looking at Here?

The list of rows below the timeline, pictured below, detail a stream of events detailing all calls affecting instances of NSLayoutConstraint. All events are listed chronologically, with the most recent events at the bottom. Each event includes the following information:

• Caller: Which class and method triggered a change to a constraint.
• Constraint: This column is the real meat and potatoes of the trace. Here you can identify which constraint is being affected, as indicated by its memory address or by the identifier property (if available). The Constraint column also contains the VFL string literal, which spells out the axis a given constraint lies along and the relationship the constraint defines.
• Constant: The constant value defined for a constraint.

• Event: Specifies what action is being taken regarding the constraint. The constraint could be created, removed or added to the window, and properties such as the identifier could be changed or removed. Possible events include:

  • Created
  • Added To Window
  • Constant Modified
  • Identifier Changed
  • Removed From Window

First, filter the list to just the objects you are interested in. In the field labeled Recorded Data, type 0x7ff4e948dce0 and 0x7ff4e948d6e0. Of course, your addresses will be different; use the ones you see. Interestingly, this field will only filter on the content of the VFL strings or memory addresses.

Now that the list is focused on the constraints we’re interested in, let’s look at the first event in the list. Beginning with #0, a constraint created by the method (_:attribute:relatedBy:toItem:attribute:multiplier:constant:). Under the Constraint column, you see the relationship and attributes that make up this constraint, UILabel:0x7ff4e948dce0.leading == UIImageView:0x7ff4e948d6e0.leading. That is, the leading edge of this instance of UILabel is set equal to the leading edge of the UIImageView. In the implementation, immediately following the creation of the constraint, its identifier property is set. Recorded in the output trace is an event where the identifier property is changed to subtitleLeadingConstraint.

Other than filtering for a memory address or constant value, you can focus on a subset of events. To do so, click and drag horizontally across the timeline at the top to specify a particular time range of events, as shown above. Similar to other instruments, you may find it helpful to drag the slider on the left edge of the Track Scale to zoom into the Stack Depth for a more detailed view of the frequency of events on the timeline.

Other Dials and Knobs

Let’s look at a couple of additional configurations provided by the tool.

To alter the visual representation of events on the timeline, open the Record Settings panel (⌘-1) and tick the Stack Depth option under Statistics to Graph.

For example, alter the timeline visual style.

For a given event, you can also view a stack trace for all message sends that led to it. Start by selecting an event, then open the Extended Detail panel (⌘-3). On the right hand panel of the instruments window, you’re presented with the stack trace for that particular event.

A Look Behind the Curtain

The value of Instruments is in its ability to offer insight into the inner workings of our code. The Cocoa Layout Instrument extends this quality to Auto Layout, providing a wealth of minute detail for each step involved in the lifetime of an interface. I look forward to seeing what additional capabilities Apple bundles with this tool.