This chapter is from the book
This chapter is from the book
This chapter is from the book
Running an Instrument
To use an instrument, you follow three steps: configuration, recording, and, optionally, saving the results.
Instrument Configuration
Configuration inspectors vary by instrument, but some elements are used frequently.
There is a Target pop-up that initially points to the document's default target (set with the Default Target menu in the toolbar). If no default target has been selected, or if the Default Target menu has been set to Instrument Specific, the instrument's Target is active. You can select from processes already running, applications that Instruments had sampled before, a new application or tool of your choice, or, with many instruments, the system as a whole.
The ability to set a target for each instrument is important: It allows you to examine the behavior of an application and other processes with which it communicates, simultaneously.
In the Track Display section, there are three controls: A Style pop-up, a Type pop-up, and a Zoom slider.
The usual Style menu selects among graphing styles for the numeric data the instrument records. These may include the following:
- Point. Each datum is displayed as a discrete symbol in the track. You can choose the symbols in the list of available series in the inspector.
- Line. The track is displayed as a colored line connecting each datum in the series. You can choose the color in the list of the available series.
- Filled Line is the same as Line, but the area under the line is colored.
- Peak shows the data collected by an instrument that records events (such as the Core Data instruments) as a vertical line at each event. Every time something happens, the trace shows a blip.
- Block is a bar graph, showing each datum as a colored rectangle. In instruments that record events, the block will be as wide as the time to the next event.
The Type menu offers two choices for instruments that can record more than one data series. Overlay displays all series on a single graph. The displayed data will probably overlap, but in point and line displays this probably doesn't matter, and filled displays are drawn translucently, so the two series don't obscure each other. Stacked displays each series in separate strips, one above the other.
Zoom increases the height of the instrument's track. This is especially handy in stacked displays, enabling you to view multiple traces without squishing them into illegibility. The slider clicks to integer multiples of the standard track height, from 1 to 10 units.
You can change the Track Display settings even after the instrument has collected its data. You can find a shortcut for the Zoom slider in the View menu, as Increase Deck Size (
+) and Decrease Deck Size (-).
One disadvantage of the inspector system is that inspectors are of fixed size, and can be quite tall. If a track is low on the screen (which it may have to be, if it is low in a multitrack document), it might run off the bottom, obscuring the Done button that dismisses the inspector. Fortunately, you can also dismiss an inspector by pressing the i button again. The only workaround that allows you to get at the options at the bottom of the inspector is to drag the track to the top of the document, make the setting, and, if you want, drag it back.
Recording
There is more than one way to start recording in Instruments.
The most obvious is to create a trace document and click the Record button in the toolbar. Recording starts, you switch to the target application, perform your test, switch back to Instruments, and click the same button, now labeled Stop.
The first time you record into a document that contains a User Interface instrument, the recording button will be labeled Record, as usual. Once the UI track contains events, the recording button is labeled Drive & Record. When you click it, no new events are not recorded into the UI track; instead, the events already there are replayed so you can reproduce your tests.
If you want to record a fresh User Interface track, open the configuration inspector (with the i button in the instrument's label) and select Capture from the Action pop-up. The recording button will revert to Record.
A second way to record is through the Quick Start feature, which allows you to start recording with a systemwide hotkey combination. To set a hotkey, open Instruments' Preferences window and select the Quick Start tab. This tab includes a table listing every system- and user-supplied template. Double-click in the column next to the template you choose, and press your desired hotkey combination. The combination must include at least two modifier keys (such as Command, Shift, and so on).
With the hotkey set, move the cursor over a window belonging to the application you want to target, and then press the key combination. Instruments will launch if it is not running already, open a new trace document behind your application with the template you selected, target it on your application, and start recording. To stop, make sure your cursor is over one of the target's windows, and press the key combination again (or switch to Instruments and click Stop).
The requirement to point the cursor at one of the target's windows allows you to run simultaneous traces on more than one application.
To remove a hotkey, select the template in the Quick Start table, and press the Delete key.
The third way to record is through the Mini Instruments window. Selecting View > Mini Instruments, or clicking the Mini button in the toolbar of any document window, hides all of Instruments' windows and substitutes a floating heads-up window listing all of the open trace documents (see Figure 26.8).
)
Figure 26.8 The Mini Instruments heads-up window. It lists each open trace document next to a clock and a recording button. Scroll through the list using the arrowheads at top and bottom.
The window lists all of the trace documents that were open when you switched to Mini mode; scroll through by clicking the up or down arrowheads above and below the list. At the left of each item is a button for starting (round icon) or stopping (square icon) recording, and a clock to show how long recording has been going on. Stopping and restarting a recording adds a new run to the document.
As with Quick Start keys, Mini Instruments has the advantages that it's convenient to start recording in the middle of an application's run (handy if you are recording a User Interface track that you want to loop) and that you can control recording without switching out of the target application (which can also impair a UI recording).
You return to the full display of Instruments by clicking the close (X) button in the upper-left corner of the Mini Instruments window.
Saving and Reopening
As with any other Macintosh document, you can save a trace document. The document will contain its instruments and all the data they've collected. There can be a lot of data, so expect a trace document to be large—on the order of tens of megabytes.
It's likely that you will come to need a uniform layout of instruments that isn't included in the default templates provided by Apple. You can easily create templates of your own, which will appear in the template sheet presented when you create a new trace document. Configure a document as you want it, and select File > Save as Template....
The ensuing save-file sheet is the standard one, focused on the directory in which Instruments looks for your templates, ~/Library/Application Support/Instruments/Templates. The name you give your file will be the label shown in the template-choice sheet. At the lower left of the sheet is a well into which you can drag an icon (for instance, if your template is for testing your application, you'd want to drop your application's icon file here), or you can click and hold the mouse button over the well to choose Apple-provided icons from a pop-up. The panel provides a text area for the description to be shown in the template-choice sheet.
- The document's suite of instruments, and their configurations, will be saved in the template.
- The template will include the default and instrument-specific targets you set.
- If you include a prerecorded User Interface track, the contents will be saved. This way you can produce uniform test documents simply by creating a new trace document and selecting the template.
As you'd expect, you can reopen a trace document by double-clicking it in the Finder, or through File > Open.... All the data is as it was when the document was saved. Clicking Record adds a new run to the document.