Saving and Importing Trace Data

Instruments provides several ways for you to save instrument and trace data for later use or reference. You can save data you’ve recorded in a trace document, or you can save the instrument configuration. Saving trace data lets you maintain a record of your app’s performance over time. Saving configurations avoids the need to recreate commonly used configurations each time you run Instruments.

The following sections explain how to save your trace documents and how to export trace data to formats that other apps can read.

Saving a Trace Document

At times, you may want to save a set of instruments along with the data that they have collected over one or more trace sessions. Instruments saves the current document as an Instruments trace file, with the .trace extension.

bullet
To save a set of instruments
  1. Select File > Save.

  2. Enter a name for the file.

  3. Enter a destination for the file.

  4. To save trace data for the most recent run only, select the Save Current Run Only checkbox. If you’ve recorded multiple runs and want to save all of that data, then deselect this checkbox.

  5. Click Save.

    ../Art/instruments_save_trace_document_2x.png

Saving an Instruments Trace Template

During your development cycle, you may need to gather trace data multiple times using a fixed set of instruments. Or, you may find yourself running the same set of instruments with the same configurations on multiple apps. Rather than setting up a new trace document and configuring it with the same set of instruments every time you run Instruments, you can build a trace document once and then save it as a trace template, allowing you to reuse it at anytime in the future.

bullet
To save a trace template
  1. Choose File > Save As Template.

  2. Enter a name for the template.

  3. Enter 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.

  4. Select an icon for the template.

  5. Enter a description for the template.

  6. Click Save.

    ../Art/instruments_save_trace_template_panel_2x.png

Once you’ve saved a template, you can open it in the same way you open other Instruments documents, by choosing File > Open. Or, if you saved it into the Instruments template folder, as mentioned above, you can open it from the template selection window.

../Art/instruments_template_selection_window_custom_tab_2x.png

When you open a trace template, Instruments creates a new trace document with the template configuration but without any data.

Exporting Track Data

Instruments allows you to export trace data to a comma-separated value (CSV) file format, a simple data file format that is is supported by many apps, including most database and spreadsheet apps. By importing data into another app, such as Numbers, you can manipulate it further, perform additional analysis, generate custom charts and graphs, compare it to other data, and more.

bullet
To export track data in CSV format
  1. Select the instrument containing the data you want to export.

  2. Choose Instrument > Export Track for ‘<Instrument Name>’

  3. Enter a name for the file.

  4. Enter a destination for the file.

  5. Click Save.

    ../Art/instruments_export_csv_window_2x.png

Instruments exports the data for the most recent run of the selected instrument.

Importing Data from the Sample Tool

If you use the sample command-line tool to do a statistical analysis of your app’s execution, you can import your sample data and view it using Instruments. Importing data from the sample tool creates a new trace document with the Sampler instrument and loads the sample data into the detail pane. Because the samples do not contain time stamp information, you can only view the data using outline mode in the detail pane. A new trace document is created based on the file you select.

bullet
To import data from the Sample tool
  1. Choose File > Import Data.

  2. Locate your saved data.

  3. Choose Sampler from the “Choose Instrument to Import Data” pop-up menu in the import window.

    ../Art/instruments_import_sample_window_2x.png
  4. Click Open.

    ../Art/instruments_trace_document_loaded_sample_2x.png

Working With DTrace Data

If your trace document contains custom instruments, you can export the underlying scripts for those instruments and run them using the dtrace command-line tool. After running the scripts, you can then reimport the resulting data back into Instruments. For information on how to do this, see Exporting DTrace Scripts.