Guides and Sample Code

Developer

Instruments User Guide

On This Page

Navigate the Timeline Pane

The most prominent portion of a trace document is the timeline pane, which presents a time-based view of the data gathered by each instrument (see Figure 11-1). This pane makes it easy to spot trends and potential problem areas in your app at a glance. For example, a spike in a memory usage graph indicates a time when your app allocated more memory than usual. This spike might be normal, or it might indicate that your code created more objects or memory buffers than you anticipated. An instrument such as Leaks can also identify where your app is not handling memory properly. If the Leaks timeline track is sparsely populated, you know that your app is behaving properly. If the track is not empty, you might want to examine why.

Figure 11-1The timeline pane of a trace document image: ../Art/instruments_trace_document_timeline_pane_2x.png

The sections that follow provide more information about the timeline pane and how you configure it.

Zoom In and Out

If you’ve captured a lot of data with a trace, you can expand or contract the detail presented in the timeline pane, allowing you to focus in on a specific subset of data (see Figure 11-2).

Figure 11-2Zooming into the timeline pane of a trace document image: ../Art/instruments_trace_document_timeline_pane_zooming_2x.png
To zoom in and out of your data

Do one of the following:

  • To zoom in or out, pinch the trackpad.

  • To zoom in or out, use the scroll wheel while pressing the Option key with the pointer positioned over the track view.

  • To zoom in, press the Option key, and drag across the section of data you wish to isolate.

  • To zoom out, press the Control key, and drag across a section of data.

To fit all recorded data in the timeline
  1. Choose View > Snap Track To Fit (or press Control-Command-Z).

    image: ../Art/instruments_view_menu_snaptracktofit_menuitem_2x.png
To increase the size of the data displayed in the timeline
  1. Choose View > Increase Deck Size (or press Command-Plus Sign).

    image: ../Art/instruments_trace_document_timeline_pane_largertrack_2x.png

    The track for the currently selected instrument increases in height, allowing you to view it in greater detail.

    image: ../Art/instruments_view_menu_increasedecksize_menuitem_2x.png
To decrease the size of the data displayed in the timeline
  1. Choose View > Decrease Deck Size (or press Command-Minus Sign).

    image: ../Art/instruments_view_menu_decreasedecksize_menuitem_2x.png

    The track for the currently selected instrument decreases in height.

Filter a Range of Data

Instruments collects massive amounts of information as it profiles. You can quickly filter this data by setting the detail pane to show only events that occurred within a specific time range. See Figure 11-3.

Figure 11-3Selecting a range of data in the timeline pane of a trace document image: ../Art/instruments_trace_document_timeline_pane_selectedrange_2x.png
To select a time range for inspection
  1. Drag across a section of data without using any modifier keys. Only the data you drag across is displayed.

    image: ../Art/instruments_trace_document_timeline_pane_selectingrange_2x.png

Instruments highlights the contents of the timeline pane that fall within the range you specified.

To clear an inspection range

Do one of the following:

  • Click outside the selected range in the timeline pane.

  • Choose View > Clear Inspection Range.

    image: ../Art/instruments_clearinspectionrange_menu_2x.png

Set Flags

Flags allow you to quickly access points of interest in the timeline pane (see Figure 11-4). You can add a name and description to each flag.

Figure 11-4Flags in the timeline pane of a trace document image: ../Art/instruments_trace_document_timeline_pane_flags_2x.png
To set a flag at the current playhead position in the timeline pane
  1. Choose Edit > Add Flag (or press Command-Down Arrow).

    image: ../Art/instruments_addflag_menu_2x.png
To navigate between your timeline flags
  1. Choose Window > Manage Flags (or press Shift-Command-T) to display the Flags palette.

    image: ../Art/instruments_manageflags_menu_2x.png
  2. Click a flag in the Flags palette to navigate to it in the timeline pane.

To delete a flag
  1. Drag the flag out of the timeline navigation bar.

To hide a flag
  1. Choose Window > Manage Flags (or press Shift-Command-T) to display the Flags palette.

    image: ../Art/instruments_manageflags_menu_2x.png
  2. Deselect the checkbox next to a flag in the Flags palette to hide it in the timeline pane.

    image: ../Art/instruments_flags_palette_disabledflag_2x.png

Access Trace Data for Multiple Runs

A trace document can record data over multiple runs of your app, as shown in Figure 11-5. When doing so, it doesn’t discard previously recorded data.

Figure 11-5Viewing multiple runs in the timeline pane of a trace document image: ../Art/instruments_strategy_pane_multipleruns_2x.png
To view a list of runs for a selected instrument
  1. Click the disclosure triangle to the left of the instrument in the strategy pane.

    image: ../Art/instruments_strategy_pane_disclosure_triangle_2x.png

    The instrument expands to display a list of runs.

To view the run data for a selected instrument
  1. Click the disclosure triangle to the left of the instrument in the strategy pane.

  2. Select the desired run’s track in the timeline pane.

To move to the next run for the selected instrument
  1. Choose Instrument > Next Run, or press Command-Single Quotation Mark (').

    image: ../Art/instruments_nextrun_menu_2x.png
To move to the previous run for the selected instrument
  1. Choose Instrument > Previous Run, or press Command-Quotation Mark (").

    image: ../Art/instruments_previousrun_menu_2x.png