---

Saving and Importing Trace Data

Instruments provides a number of 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 application’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 applications can read.

In this section:

Saving a Trace Document
Saving an Instruments Trace Template
Exporting Track Data
Importing Data from the Sample Tool
Working With DTrace Data

Saving a Trace Document

To save a set of instruments together with the data that they have collected over one or more trace sessions, choose File > Save. Instruments saves the current document as an Instruments trace file, with the .trace extension.

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 application 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. Choose File > Save As Template to save your document’s current instruments and configuration (including any user interface tracks) as a template.

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 that 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 applications 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. To open it, choose it from the Run > Start with Performance Tool menu.

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 applications. For example, you might save your trace data in this format so that you can import it into a spreadsheet application.

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 program’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.

To import data, choose File > Import Data. Instruments prompts you to select the text file containing the sample data. It then creates a new trace document based on the file you select.

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

---