Xcode Instruments

Also known as: Instruments

On this page 7

Xcode Instruments, usually called simply Instruments, is the performance analysis and tracing tool that ships with Apple’s Xcode development environment. It records what an app and the operating system do over time, including CPU sampling, memory allocations, hangs, animation hitches and energy use, and displays the data on a shared timeline for iOS, iPadOS, macOS, watchOS, tvOS and visionOS apps.

In mobile performance work, Instruments is the primary way to turn a vague complaint such as “the app feels slow” into measurable evidence: a specific function, allocation pattern or blocked thread that explains the problem. It complements field data from crash analytics and app metrics by showing why a regression happens on a device in front of the developer.

How Instruments records and presents a trace

Instruments works by attaching a set of data-collecting instruments to a running process or to a whole device and saving the result as a trace document. Each instrument contributes one or more tracks to the timeline, and selecting a time range filters every detail view to that window.

Most data comes from kernel-level tracing and periodic sampling rather than from code changes in the app. The Time Profiler, for example, captures the call stack of every running thread at a fixed interval, typically about one millisecond, and aggregates the samples into a call tree weighted by time. Developers can add their own markers with signposts through the os_signpost API, which appear as labeled intervals next to system data.

A session is usually started with Product, then Profile in Xcode, which builds the app in a release-like configuration and opens the template chooser. The command-line tool xctrace records the same traces in scripts and continuous integration.

Core templates and what each one measures

Instruments offers templates, which are preconfigured groups of instruments aimed at one class of problem. Choosing the right template is the first decision in any profiling session, because each one balances detail against recording overhead differently.

The table below lists the templates most often used for mobile apps.

TemplateWhat it measuresTypical question answered
Time ProfilerSampled call stacks per threadWhich code consumes CPU time
AllocationsHeap allocations and object lifetimesWhy memory keeps growing
LeaksUnreachable memory blocksWhich objects are never freed
App LaunchProcess start to first frameWhat delays startup
Animation HitchesLate frames and render phasesWhy scrolling stutters
HangsMain-thread unresponsive intervalsWhat blocks user input
System TraceThread states, syscalls, schedulingWhy a thread is waiting
Metal System TraceGPU workload and command buffersWhere graphics frames lose time
Frequently used Instruments templates

Further templates cover network activity, file activity, SwiftUI view updates, Core Data and energy impact. Developers can also build custom instruments that turn their own signpost data into dedicated tracks.

Key metrics and thresholds to read in a trace

A trace is only useful when its numbers are compared against meaningful thresholds. Apple publishes guidance for responsiveness and smoothness, and experienced teams add budgets of their own for startup and memory.

The following values are common reference points. They are guidelines rather than hard limits, and budgets should reflect the oldest device a team supports.

MetricReference valueWhy it matters
Hang duration250 ms or longer is reported as a hangUsers notice a frozen interface
Hitch time ratioUnder 5 ms per second is goodHigher ratios feel like stutter
Frame budget at 60 HzAbout 16.7 ms per frameMissed budgets drop frames
Frame budget at 120 HzAbout 8.3 ms per frameProMotion displays halve the budget
Cold launch timeAim for well under 1 second to first frameSlow launches raise abandonment
Common performance reference values

Main-thread work deserves the closest attention, because interface updates and touch handling run there. A short spike on a background thread is usually harmless, while the same spike on the main thread can cause a visible hitch.

How Instruments compares with other profiling tools

Instruments is one tool among several, and each tool covers a different stage of performance work. Lightweight gauges in the Xcode debugger show trends, while Instruments provides the deep, time-correlated view needed for diagnosis.

ToolData sourceBest use
Xcode InstrumentsLocal device or simulator traceDeep diagnosis of a reproducible issue
Xcode debug gaugesLive debugger sessionQuick check of CPU and memory trends
MetricKit and Xcode OrganizerAggregated field reportsSpotting regressions across real users
Android Studio ProfilerAndroid device traceEquivalent role on Android
PerfettoSystem-wide Android tracingCross-process analysis on Android
Instruments and related performance tools

A sound workflow uses field data to find the problem and Instruments to explain it. The reverse also holds: after a fix, field metrics confirm whether the improvement reached real users across device models.

Profiling practices and common mistakes

Accurate profiling depends more on test conditions than on the tool itself. The most reliable results come from a physical device, a release build and a repeatable scenario recorded several times.

  • Profiling in the simulator gives misleading CPU and GPU numbers, because it runs on Mac hardware.
  • Debug builds disable compiler optimizations and can exaggerate hot spots that disappear in release.
  • Testing only on the newest phone hides problems that appear on older chips with less memory.
  • Recording too many instruments at once adds overhead and can distort timing-sensitive results.
  • Ignoring thermal state makes later runs slower than earlier ones, so results should note device temperature.

Teams that profile regularly also save baseline traces for key flows such as launch and feed scrolling, which makes performance regressions much easier to spot after each release.

The short version

Xcode Instruments is a recorder for app behavior. While an app runs, it writes down what the processor, memory and screen are doing, moment by moment.

Think of it as a dashboard camera for software. When something feels slow, the developer replays the recording. Then the exact moment and the exact cause become visible, instead of a guess. The fix can then target the real problem.

Where it makes a difference

A team maintaining a shopping app receives reviews saying that the product feed stutters on older iPhones. Field metrics confirm a high hitch rate on devices with older chips, but the cause is unclear. A developer records the feed on an older test phone with the Animation Hitches and Time Profiler templates in a release build.

The trace shows that each new product cell decodes a full-resolution image on the main thread, taking about 30 ms and missing two frames at 60 Hz. The team moves decoding to a background queue and requests thumbnails sized to the cell. A second trace shows the hitch time ratio falling below 5 ms per second, and the stutter complaints largely stop after the next update.