Adding and Configuring Instruments

The Instruments tool uses instruments to collect data and display that data to the user. Although there is no theoretical limit to the number of instruments you can include in a document, most documents contain fewer than ten for performance reasons. You can even include the same instrument multiple times, with each instrument version configured to gather data from a different process on the system.

Instruments comes with a wide range of built-in instruments whose job is to gather specific data from one or more processes. Most of these instruments require little or no configuration to use. You simply add them to your trace document and begin gathering trace data. You can also create custom instruments, however, which provide you with a wide range of options for gathering data.

This chapter focuses on how to add existing instruments to your trace document and configure them for use. For information on how to create custom instruments, see “Creating Custom Instruments.”

Viewing the Built-in Instruments with the Library Window

The instrument library (shown in Figure 3-1) displays all of the instruments that you can add to your trace document. The library includes all of the built-in instruments plus any custom instruments you have defined.

Figure 3-1  The instrument library
The instrument library
To open the Library window

Do one of the following:

  • Click the Library button in the toolbar.

  • Choose Window > Library.

Because the list of instruments in the Library window can get fairly long—especially if you add your own custom-built instruments—the instrument library provides several options for organizing and finding instruments. The following sections discuss these options and show how you use them to organize the available instruments.

Changing the Library View Mode

The library provides different view modes to help you organize the available instruments. View modes let you choose the amount of information you want displayed for each instrument and the amount of space you want that instrument to occupy. Instruments supports the following view modes:

  • View Icons. Displays only the icon representing each instrument.

  • View Icons And Labels. Displays the icon and name of each instrument.

  • View Icons and Descriptions. Displays the icon, name, and full description of each instrument.

  • View Small Icons And Labels. Displays the name of the instrument and a small version of its icon.

To change the library’s view mode, select the desired mode from the Action menu at the bottom of the Library window.

In addition to changing the library’s view mode, you can display the parent group of a set of instruments by choosing Show Group Banners from the Action menu. The Library window organizes instruments into groups, both for convenience and to help you narrow down the list of instruments you want. By default, this group information is not displayed in the main pane of the Library window. Enabling the Show Group Banners option adds it, making it easier to identify the general behavior of instruments in some view modes.

Finding an Instrument in the Library

By default, the Library window shows all available instruments. Each instrument, however, belongs to a larger group, which identifies the purpose of the instrument and the type of data it collects. To limit the number of instruments displayed by the Library window, use the group selection controls at the top of the Library window to select fewer groups. When there are many instruments in the library, this feature makes it easier to find the instruments you want.

The group selection controls have two different configurations. In one configuration, the Library window displays a pop-up menu, from which you can select a single group. If you drag the split bar between the pop-up menu and the instrument pane downward, however, the pop-up menu changes to an outline view. In this configuration, you can select multiple groups by holding down the Command or Shift key and selecting the desired groups.

Figure 3-2 shows both standard mode and outline mode in the Library window. The window on the left shows standard mode, in which you select a single group using the pop-up menu. The window on the right shows the outline view, in which you can select multiple groups and manage your own custom groups.

Figure 3-2  Viewing an instrument group
Viewing an instrument group

Another way to filter the contents of the Library window is to use the search field at the bottom of the Library window. Using the search field, you can quickly narrow down the contents of the Library to find the instrument or instruments whose name, description, category, or list of keywords matches the search text. For example, Figure 3-3 shows instruments that match the search string file.

Figure 3-3  Searching for an instrument
Searching for an instrument

When the pop-up menu is displayed at the top of the Library window, the search field filters the contents based on the currently selected instrument group. If the outline view is displayed, the search field filters the contents based on the entire library of instruments, regardless of which groups are selected.

Creating a Custom Group

Create a group of instruments to customize your data gathering and streamline your data gathering efforts.

To create a static group in the Library window
  1. Click Library to open the Library window.

  2. Control-click in the Library window.

  3. Choose New Group.

  4. Enter a name for the group and press Return.

  5. Select the Library directory.

  6. Drag the desired instruments into the new group.


When you first open the Library window, the library directory and all previously created groups are displayed. The library directory contains a complete list of all available instruments.

Populate a new group with any number of instruments from the library directory. Give the group a name that identifies its purpose so you can easily select it when needed. You can nest groups in a hierarchical structure. You can also drag a nested group outside the structure to stand alone. If an instrument has already been put into a group, the group name does not become highlighted if you try to drag the same instrument into it a second time.

Creating a Smart Group

Smart groups are instruments that have been grouped together based on a set of user-created rules.

To create a smart group
  1. Choose New Smart Group from the Library window’s action menu.

  2. Enter a name for the group in the Label field.

  3. Specify a rule for the group.

  4. Click the plus button (+) to create a new rule.

  5. Verify that the group populated correctly.


Every smart group must have at least one rule. You can add additional rules, as needed, using the controls in the rule editor and then configuring the group to apply all or some of the rules. Table 3-1 lists the criteria you can use to match instruments.

Table 3-1  Smart group criteria




Matches instruments based on their title. This criterion supports the comparison operators Starts With, Ends With, and Contains.

Used Within

Matches instruments based on when they were used. You can use this criterion to match only instruments that were used within the last few minutes, hours, days, or weeks.

Search Criteria Matches

Matches instruments whose title, description, category, or keywords include the specified string.


Matches instruments whose library group name matches the specified string. This criterion does not match against custom groups.

To edit an existing smart group, select the group in the Library window and choose Edit groupname from the action menu, where groupname is the name of your smart group. Instruments displays the rule editor again so that you can modify the existing rules.

To remove a smart group from the Library window, select the group and choose Remove Group from the action menu. If you are currently viewing groups using the outline view, you can also select the group and press the Delete key.

Adding an Instrument

Expand on the amount and type of data collected by adding a new instrument to your trace document.

To add an instrument from the Library window
  1. Click Library to open the Library window.

  2. Select the Library directory.

  3. Double-click an instrument to add it to the trace document.

You can place multiple instances of an instrument in your trace document with each one set up to collect data from a different process or app. In this way, you can track how a client and server interact with each other.

Configuring an Instrument

Most instruments are ready to use as soon as you add them to the Instruments pane. Some instruments can also be configured using the instrument inspector. The content of the inspector varies from instrument to instrument. Most instruments contain options for configuring the contents of the track pane, and a few contain additional controls for determining what type of information is gathered by the instrument itself.

To open the configuration options for an instrument

Do one of the following:

  • Click the inspector icon to the right of the instrument’s name.

  • Choose File > Get Info.

  • Press Command-I.

Controls related to displaying information in the track pane can be configured before, during, or after your record data for the track. Instruments automatically gathers the data it needs for each display option regardless of whether that option is currently displayed in the track pane.

For a list of instruments, including their configurable options, see Instruments User Reference.