---

Introduction to Instruments User Guide

Contents:

Organization of This Document
Getting the Xcode Tools

Instruments is an application for dynamically tracing and profiling Mac OS X code. It is a flexible and powerful tool that lets you track one or more processes and examine the collected data. In this way, Instruments helps you understand the behavior of both user programs and the operating system.

With the Instruments application, you use special tools (known as "instruments”) to trace different aspects of a process’ behavior. You can also use the application to record a sequence of user interface actions and replay them, using one or more instruments to gather data.

The Instruments application includes the ability to:

• Examine the behavior of one or more processes

• Record a sequence of user actions and replay them, reliably reproducing those events and collecting data over multiple runs

• Create your own custom DTrace instruments to analyze aspects of system and application behavior

• Save user interface recordings and instrument configurations as templates, accessible from Xcode

Using Instruments, you can:

• Track down difficult-to-reproduce problems in your code

• Do performance analysis on your program

• Automate testing of your code

• Stress-test parts of your application

• Perform general system-level troubleshooting

• Gain a deeper understanding of how your code works

Instruments is available with Xcode 3.0 and Mac OS X 10.5 and later.

This document describes the Instruments user interface and gives an overview of how to use the Instruments application to trace processes and view data. It is intended for developers and system administrators who want to use Instruments to better understand the behavior of their programs or of the system as a whole.

Organization of This Document

The following chapters describe how to use the Instruments application:

• “Instruments Quick Start” gives a brief overview of the Instruments application and introduces the main window.

• “Adding and Configuring Instruments” describes how to add and configure instruments and run them to collect data on one or more processes. This chapter also shows how to choose the program to trace.

• “Recording Trace Data” describes the ways you can initiate traces and gather trace data.

• “Working with a User Interface Track” describes how to record and replay a sequence of user actions.

• “Viewing and Analyzing Trace Data” describes the tools you use to view the data returned by the instruments.

• “Saving and Importing Trace Data” describes how you save trace documents and data and how you import data from other sources.

• “Creating Custom Instruments with DTrace” shows how to create and configure your own DTrace-based custom instrument.

• “Built-in Instruments” describes the instruments that ship with Instruments.

Getting the Xcode Tools

Instruments is part of the Xcode Tools, a comprehensive suite of developer tools for creating Mac OS X software. The Xcode Tools include applications to help you design, create, debug, and optimize your software. This tools suite also includes header files, sample code, and documentation for Apple technologies. You can download the Xcode Tools from the members area of the Apple Developer Connection (ADC) website (http://connect.apple.com/). Registration is required but free.

---