Guides and Sample Code


Instruments User Guide

On This Page

Create, Save, and Open Trace Documents

In Instruments, all work is done in a trace document, which contains a set of instruments, their configured settings, and the data they have collected. Once you profile an app with a trace document, you can save the document to preserve the trace data you have gathered and open it again later for viewing and analysis.

About Profiling Templates

When Instruments first starts up, it provides a list of profiling templates (see Figure 6-1). Each template contains a collection of instruments that are commonly used together to analyze an app and gather useful information in order to help identify problems or make your app more efficient.

Figure 6-1The profiling template selection dialog image: ../Art/instruments_profilingtemplate_dialog_2x.png

You should plan to use a profiling template as a starting point whenever you need to collect data for a particular purpose. For example, if you want to check your app for memory problems, you should choose a memory-related template, such as Allocations, Leaks, or Zombies. After using a template to create a trace document, you can always add or remove individual instruments, or reconfigure instruments, as needed.

For a complete list of available templates and the instruments they contain, see Profiling Templates.

Create a Trace Document

You need to create a trace document to begin profiling with Instruments.

To create a trace document
  1. Launch Instruments.

  2. In the profiling template selection dialog that appears, select a target device and process.

    image: ../Art/instruments_profiling_dialog_target_2x.png
  3. Select the desired profiling template.

    image: ../Art/instruments_profiling_dialog_template_choice_2x.png
  4. Click Choose.

A new document is created with the preconfigured instruments from the template you chose.

Save a Trace Document

Once you’ve created a trace document, you can save it for later reference. Instruments saves trace documents as Instruments trace files with the .trace extension.

To save a trace document
  1. Create a trace document. See To create a trace document.

  2. Choose File > Save. Or, choose File > Save As if you want to save a previously saved trace document as a new file.

    image: ../Art/instruments_save_menu_2x.png
  3. Enter a name for the file.

    image: ../Art/instruments_save_dialog_2x.png
  4. Choose a destination for the file.

  5. Click Save.

Save a Trace Document as a Profiling Template

If you create a trace document you think you might need again for profiling other apps, you can save it as a custom template so you don’t have to recreate it each time you run Instruments.

To save a trace document as a profiling template
  1. Create or open a trace document. See To create a trace document.

  2. Choose File > Save As Template.

    image: ../Art/instruments_saveastemplate_menu_2x.png
  3. Enter a name for the template.

    image: ../Art/instruments_savetemplate_dialog_2x.png
  4. Choose a destination for the template.

    Save your template in the /Users/<username>/Library/Application Support/Instruments/Templates directory to make it available in the custom section of the Instruments template window. This is the default directory in the Save As Template dialog.

  5. Select an icon for the template.

  6. Enter a description for the template.

  7. Click Save.

    Once you save a template, it automatically appears in the profiling template selection dialog, grouped with the Custom templates. Next time you create a trace document, you can select it as your starting point.

    image: ../Art/instruments_customprofilingtemplate_2x.png

Close a Trace Document

To close an opened trace document
  1. Choose File > Close (or press Command-W).

    image: ../Art/instruments_file_close_menu_2x.png
  2. If your document contains unsaved data, select whether to save the updated document.

    image: ../Art/instruments_close_save_changes_dialog_2x.png

The document closes.

Open a Trace Document

To open a saved trace document

Do one of the following:

  • Double-click the .trace document file in the Finder.

    image: ../Art/trace_document_2x.png
  • Drag the .trace document file onto the Instruments app icon.

    image: ../Art/instruments_drag_and_open_trace_doc_2x.png
  • Open Instruments and perform the following steps:

    1. Choose File > Open (or press Command-O).

      image: ../Art/instruments_file_open_menu_2x.png
    2. Locate a saved .trace document file.

      image: ../Art/instruments_open_trace_doc_dialog_2x.png
    3. Click Open.

The trace document opens in Instruments.