Guides and Sample Code


Instruments User Guide

On This Page

Access and Use Individual Instruments

Within a trace document, individual data collection modules known as instruments collect data about an app, process, or device over time. Each instrument collects and displays a specific type of information, such as file access, memory use, or network activity. Instruments includes an extensive library of instruments, which are designed to meet the needs of most developers. Advanced developers, however, can also develop their own custom instruments that use DTrace to gather other kinds of data.

Display the Library Palette

The Library palette (Figure 8-1) displays all of the instruments you can add to a trace document. The library includes all of the built-in instruments as well as any custom instruments you may have defined.

Figure 8-1The Library palette image: ../Art/instruments_library_palette_2x.png
To display the Library palette

Do one of the following:

  • Click the Add Instrument button (+) in the trace document toolbar.

  • Choose Window > Library (or press Command-L).

    image: ../Art/instruments_library_menu_2x.png

Find Instruments in the Library Palette

The list of instruments in the Library palette is quite long, especially if you’ve added your own custom instruments. Use the filter field at the bottom of the Library palette to quickly find a specific instrument based on its name, description, or keywords (see Figure 8-2).

Figure 8-2Filtering for instruments in the Library palette image: ../Art/instruments_library_palette_filterterm_2x.png

Change the Library View Mode

The instruments in the Library palette can be viewed as icons with or without names and descriptions. Click the icon view button (image: ../Art/icon_library_palette_iconview_2x.png) at the bottom of the library palette to display only the icon for each instrument (see Figure 8-3). To display the icon, name, and description of each instrument again, click the list view button (image: ../Art/icon_library_palette_listview_2x.png).

Figure 8-3The library palette in icon view image: ../Art/instruments_library_palette_iconview_2x.png

Add an Instrument to a Trace Document

Whether you’ve created a trace document that’s based on a template or a blank trace document, you can add new instruments to it in order to expand its functionality.

To add an instrument to a trace document
  1. Open the desired trace document.

  2. Display the Library palette.

  3. Find the desired instrument.

  4. Drag the instrument from the Library palette to the desired position in the strategy pane instruments list in your trace document.

    image: ../Art/instruments_trace_document_addinstrument_2x.png

Remove an Instrument from a Trace Document

When working in a trace document, you can easily remove instruments you don’t need anymore.

To remove an instrument from a trace document
  1. Open the desired trace document.

  2. Select the instrument you want to delete in the strategy pane instruments list.

    image: ../Art/instruments_trace_document_selectedinstrument_2x.png
  3. Press the Delete key, or choose Instrument > Delete instrumentname Instrument.

    image: ../Art/instruments_deleteinstrument_menu_2x.png
  4. When prompted, click OK to confirm that you really want to remove the instrument.

    image: ../Art/instruments_deleteinstrumentconfirmation_dialog_2x.png

Configure an Instrument’s Record Settings

Instruments are typically ready to use as soon as you add them to a trace document. In some cases, however, you might need to customize the settings for an instrument. For example, you may wish to adjust the sampling rate for the Activity Monitor instrument or discard events for free memory while profiling with the Allocations instrument. Customizable settings like these vary, depending on the instrument. Many instruments contain controls for determining what type of information is gathered by the instrument itself. You can adjust these settings in the record settings area of the inspector pane (see Figure 8-4).

Figure 8-4Record settings for the Activity Monitor instrument image: ../Art/instruments_inspector_pane_record_settings_2x.png

Configure an Instrument’s Display Settings

After recording a trace, Instruments displays the results in the detail pane. These results vary from instrument to instrument. They may include things like a summary, a call tree, and a sample list. Often, a lot of data is presented here, and navigating it can be time consuming. To help get you to the right information quickly, Instruments often (again, it depends on the instrument) allows you to make adjustments to and filter down the information displayed. If an instrument supports these operations, they appear in the display settings area of the inspector pane (see Figure 8-5). Options for configuring the contents of the timeline pane are also found here.

Figure 8-5Display settings for the Activity Monitor instrument image: ../Art/instruments_inspector_pane_display_settings_2x.png