About Instruments

Instruments Overview: Instruments is a powerful and flexible performance-analysis and testing tool that’s part of the Xcode tool set.

About the trace document: A trace document is used to organize and configure instruments for profiling, initiate data collection, and view and analyze the results.

About the trace document toolbar: The toolbar of the trace document lets you start, pause, and stop data profiling, add instruments, hide and show panes, and more.

About the trace document timeline pane: The timeline pane displays a graphical summary of the instrument, CPU, and thread data recorded for a given trace.

About the display configuration popover: Use the display configuration popover to configure the format of the data and to configure the information displayed in the timeline.

About the trace document detail pane: The detail pane shows detailed information about the data collected by the instruments in your trace document.

About the trace document inspector pane: The inspector pane contains information about the selected recording and extended detail for some instruments.

About the Library palette: The Library palette provides a complete list of available instruments and lets you add them to your trace documents.

About the Flags palette: The Flags palette lets you see, enable, and disable any flags you may have applied in the timeline pane of the active trace document.

About profiling templates: A profiling template is a trace document that’s preconfigured with instruments and settings for performing a common type of trace.

About the profiling template selection dialog: The profiling template selection dialog lets you choose a profiling template, a file containing a set of preconfigured instruments.

About the Preferences window: The preferences window is used to control various settings related to the behavior of Instruments.

Launch Instruments

Launch Instruments from the Xcode menu: The most direct way to launch Instruments is by choosing Xcode > Open Developer Tool > Instruments in Xcode.

Launch Instruments from the Dock: Control-click the Xcode icon in the Dock, and then choose Options > Open Developer Tool > Instruments from the shortcut menu to launch Instruments.

Add Instruments to your Dock: Launch Instruments, Control-click its icon in the Dock, and choose Options > Keep in Dock from the shortcut menu

Add Instruments to Launchpad: Place an alias to the Instruments app in your /Applications folder to make it appear in Launchpad.

Launch Instruments from the command line: You can use the ‘open’ command, followed by the path to the Instruments app, to launch Instruments from the command line.

Create, save, and open trace documents

Create a trace document: Launch Instruments and choose a template in the profiling template selection dialog to create a new trace document.

Save a trace document: Choose File > Save or File > Save As to save a trace document to the desired destination for later reference.

Save a trace document as a profiling template: Choose File > Save As Template to save an open trace document as a custom template you can reuse.

Open a trace document: Double-click a saved trace document file or drag it onto Instruments to open it, or choose File > Open and select a saved trace document file.

Close a trace document: Choose File > Close to close a trace document when you’re done working with it.

Target devices and processes

Target a device and process: Target a specific device and process for profiling by choosing from the target lists in the toolbar of a trace document.

Target an iOS device: Connect an iOS device to your development Mac and select it from the target device list to begin profiling it.

Enable an iOS device for wireless profiling: Connect an iOS device to your development Mac with a cable, press the Option key, and select the device in the target device list to enable wireless profiling.

Prepare an Apple Watch for profiling: Use Xcode and an iPhone to prepare a paired Apple Watch for profiling with Instruments.

Access and use Instruments

Display the Library palette: Use the Library palette to browse available instruments and drag them to a trace document.

Filter for a specific instrument in the Library palette: Type into the filter field at the bottom of the Library palette to look for a specific instrument.

Add an instrument to a trace document: Drag instruments from the Library palette to a trace document.

Remove an instrument from a trace document: Remove an instrument from a trace document by selecting it in the instrument list and pressing the delete key.

Configure an instrument’s display settings: Configure the timeline display settings for an instrument using the display configuration popover. Configure the detail pain settings for an instrument using display configuration controls in the filter and configuration bar.

Record, pause, and stop traces

Record a trace: Click the Record button in the trace document toolbar to begin profiling your app.

Configure recording options: Choose File > Record Options to configure the global data collection behavior of a trace document, and to configure the profiling behavior of an instrument and adjust the data it collects.

Pause a trace: Click the Pause button in the trace document toolbar to pause an active recording.

Stop a trace: Click the Stop button in the trace document toolbar to stop an active recording.

Profile your app from the Xcode Build and Product menus: Choose Profile from the build menu in the Xcode main window or from the Product menu in the menu bar to begin profiling your app with Instruments.

Use a default template to profile from the Xcode build and product menus: Choose a default profiling template for your app from the Xcode scheme editor dialog.

Profile from the Xcode gauges while debugging: Click a profiling button in an Xcode debug navigator gauge to transition monitoring of your app over to Instruments.

Profile from the Dock: Control-click the Instruments icon in the Dock and choose an option from the shortcut menu to initiate profiling.

Profile with the instruments command-line tool: Use the ‘instruments’ command-line tool in Terminal to profile an app and save the collected data in a trace file, which can be opened in Instruments for evaluation.

Run a trace in deferred mode: Choose File > Recording options and enable deferred mode to perform extremely precise data collection with Instruments.

Run Instruments in deferred mode: Permanently enable deferred mode, which increases accuracy when doing performance profiling, in the Recording pane of Instruments preferences.

Navigate collected data

Zoom in and out in the timeline pane: Pinch the trackpad, use the scroll wheel while pressing the Option key, or press Option or Control and drag across a section of data in the timeline pane to zoom in and out.

Filter a range of data in the timeline pane: Drag across a portion of the timeline pane to isolate the events that occurred at that time and display them in the detail pane.

Set flags in the timeline pane: Place flags in the timeline pane to mark areas of interest for analysis.

Pin and unpin a timeline: Move the pointer over the left side of the instrument and click the pin or unpin button.

View different types of data in the detail pane: Use the navigation bar of the detail pane to switch between different types of collected data.

Use the extended detail pane: Use the extended detail area in the inspector pane to see a stack trace or other information for some recorded events.

Access trace data for multiple runs: Choose Instrument > Previous Run or Instrument > Next Run to show the data for different runs.

Access source code from Instruments: Show your symbols in Xcode by Control-clicking on a user symbol in the detail pane, and choosing Reveal in Xcode from the popover.

Configure Instruments

Map data to source code: Choose File > Symbols and locate a dSYM file to provide Instruments with a list of symbols associated with your app.

Set General preferences: Choose Instruments > Preferences and click General to configure basic Instruments behavior such as startup options, keyboard shortcuts, and warning options.

Set Recording preferences: Choose Instruments > Preferences and click Recording to configure how tracks are displayed in your trace documents.

Set CPUs preferences: Choose Instruments > Preferences and click CPUs to specify the CPU configuration of your device.

Set Symbols preferences: Choose Instruments > Preferences and click Symbols to configure global search paths for symbols in Instruments.

Profile your app’s performance

Track CPU core and thread use: The Time Profiler profiling template performs low-overhead, time-based sampling of processes running on the system’s CPUs.

Look for performance bottlenecks: The Counters profiling template finds bottlenecks in your app by identifying an excessive number of events of particular types.

Use Activity Monitor to track overall network and disk use: The Activity Monitor profiling template tracks overall system activity over time, including CPU, memory, network, and disk.

Monitor network connections of an iOS app: The Network profiling template analyzes your iOS app’s TCP/IP and UDP/IP connections.

Monitor disk use in macOS: The File Activity profiling template monitors and reports your OS X app’s disk use.

Profile your app’s memory usage

Find abandoned memory: The Allocations profiling template measures heap memory usage and tracks allocations, including specific object allocations by class.

Find memory leaks: The Leaks profiling template measures memory usage in your app and identifies memory that has been allocated to objects that are no longer referenced and reachable.

Finding zombies: The Zombies profiling template measures memory usage in your app and identifies objects that are called after they’ve been released and no longer exist.

Profile your app’s energy

Measure the energy impact of an iOS device: The Energy Log profiling template monitors a variety of factors that affect energy usage on an iOS device, including CPU activity, network activity, screen brightness, and more.

Log energy usage directly on an iOS device: Enable energy logging on your iOS device to record energy-related data unobtrusively while the device is used, without tethering it to Instruments.