Saving and Importing Trace Data

Instruments provides several ways for you to save instrument and trace data. For a given Instruments document window, you can save the trace data you’ve recorded with that document or you can save the instrument configuration of that document. Saving the trace data lets you maintain a record of your app’s performance over time. Saving the document configuration avoids the need to recreate a commonly used configuration each time you run Instruments.

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

Saving a Trace Document

At times you will 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. Click Save.

By default, Instruments saves only the trace data collected on the most recent run. If you have recorded multiple runs and want Instruments to save all of that data, you must deselect the Save Current Run Only option in the General pane of Instruments preferences before saving the document.

Saving an Instruments Trace Template

During your development cycle, you may want to gather data at several points by running Instruments on your app using a fixed set of instruments. Rather than reconfigure the same set of instruments in your trace document each time you run Instruments, you can configure the trace document once and save it as a trace template.

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.

  4. Select an icon for the template.

  5. Enter a description for the template.

  6. Click Save.

Trace template documents are not the same as the Instruments templates that appear when you create a new document. You open a trace template in the same way you open other Instruments documents, by choosing File > Open. When you open a trace template, Instruments creates a new trace document with the template configuration but without any data.

Xcode supports launching your apps using your custom trace templates. To add your trace template to the Run menu in Xcode, drop the template in the /Users/<username>/Library/Application Support/Instruments/Templates directory on your local system.

Exporting Track Data

Instruments lets you export trace data to a comma-separated value (CSV) file format. This simple data file format is supported by many apps. For example, you might save your trace data in this format so that you can import it into a spreadsheet app.

To save your trace data to a CSV file, select the instrument whose data you want to export and choose Instrument > Export Data for: <Instrument Name>. Instruments exports the data for the most recent run of that 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. And although you can use the Call Tree configuration options of the Sampler instrument to trim the sample data, you cannot prune data using the Call Tree Constraints or Inspection Range controls. 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. Click Save.

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.”