Instruments — what it is, Time Profiler and Allocations capabilities

What is Instruments?

Instruments is a profiling and tracing system included in Xcode and based on DTrace technology developed by Sun Microsystems. Instruments combines dozens of profiling tools (templates) in a single interface: simply select a template, launch your app through Xcode and start collecting data.

Instruments architecture is built on a client-server model: an agent on the device collects data and transmits it to the Mac via USB connection. This minimizes the profiler’s impact on application performance — Instruments operates primarily on the host side. According to WWDC 2022, the Time Profiler overhead at 1 ms sampling frequency is less than 3%.

Instruments supports custom templates — the developer can combine multiple instruments in a single profiling session. For example, simultaneously run Time Profiler + Allocations + Leaks and see the correlation between CPU spikes and memory allocations. This provides a holistic performance picture unavailable when analyzing each component in isolation.

Which templates are available by default

Xcode ships with 16 preset Instruments templates: Time Profiler, Allocations, Leaks, Energy Log, Network, Core Animation, Metal System Trace, File Activity, System Trace and others. Each template is optimized for a specific task and pre-configured with the correct trigger and filter settings.

Time Profiler: CPU Performance Analysis

Time Profiler is the most used Instruments template. It works by sampling the call stack: every 1–10 milliseconds the system records the call stack of all application threads. After stopping the session, Instruments aggregates the samples and shows which methods and functions consumed the most time. The result is presented as a Call Tree — a call tree sorted by Self Weight.

The key metric of Time Profiler is Self Weight (time spent directly in the method, excluding calls to child methods). Self Weight shows which functions are actually loading the CPU. Weight (total time with child methods) can be misleading: a method with high Weight may simply be calling another slow method while being fast itself.

import UIKit

class ImageGalleryViewController: UIViewController {
    // Time Profiler will show that cellForItemAt has Self Weight = 40%
    // inside it decodeImage takes 35% — this is the bottleneck

    func collectionView(
        _ collectionView: UICollectionView,
        cellForItemAt indexPath: IndexPath
    ) -> UICollectionViewCell {
        let cell = collectionView.dequeueReusableCell(
            withReuseIdentifier: "ImageCell",
            for: indexPath
        ) as! ImageCell
        // ❌ decodeImage — bottleneck (Self Weight = 35%)
        cell.imageView.image = UIImage(contentsOfFile: imagePath)
        return cell
    }
}

When analyzing Time Profiler, pay attention to methods running on com.apple.main-thread. If Self Weight on the main thread exceeds the 16 ms per frame threshold, the UI will stutter. The solution to such problems is moving image decoding, layout calculations and data processing from the main thread to a background thread via Grand Central Dispatch (GCD).

How to read the Call Tree in Time Profiler

Call Tree is a hierarchical representation of all method calls, sorted by Self Weight. The heaviest method in the Call Tree is the first line. Expanding the line shows which child methods were called and how much time they took. Look for methods where Self Weight (own time) significantly exceeds Weight (total time) — these are signs of synchronous locks and waiting.

Allocations: Real-Time Memory Tracking

Allocations is a tool for monitoring all memory allocations of an application. It shows which objects, in what quantity and with what total size are created at each moment. Unlike Memory Profiler in Android Studio, Allocations supports Heapshot — a snapshot of live objects with the ability to compare two snapshots.

The Allocations interface consists of two main sections: All Allocations (total statistics by all object types) and Call Trees (call tree broken down by methods that create objects). To find leaks, use Heapshot Analysis: take a snapshot before executing a scenario, execute the scenario, take a snapshot after — and compare which new objects remain in memory.

According to Apple Developer Documentation, the most common leak pattern detected through Allocations is excessive creation of UIView and CALayer during collection scrolling. If the number of live UIView grows with each scroll while the collection reuses cells — somewhere additional views are being created without releasing old ones. Allocations shows the exact call stack where these views are created.

Heapshot Analysis: Comparing Memory Snapshots

Heapshot is a snapshot of live objects in Allocations. Take a Heapshot before executing a scenario, execute the scenario and take a second Heapshot. The difference between the snapshots will show which objects were created and not released. The ideal result is growth of only temporary objects (Autorelease pool). For accurate analysis, use a combination of Allocations + Leaks in a single session. Allocations shows which objects are not being released, and Leaks shows why (which strong reference is holding them). Run a dual session whenever you suspect a leak.

Leaks: Automatic Memory Leak Detection

Leaks is a specialized tool for detecting memory leaks in iOS and macOS applications. Unlike Allocations, which simply shows allocations, Leaks actively scans the heap looking for retain cycles — situations where two or more objects mutually hold each other with strong references.

Leaks works together with Cycles & Roots — a visualizer of the object retention graph. When a leak is detected, Leaks shows all objects in the cycle, their retain count and the exact fields through which references are passed. The developer simply needs to look at the graph and understand which reference needs to be changed to weak.

The tool automatically highlights leaks with a red marker on the timeline. Leaks works in real time: as soon as the system detects a leak, it immediately signals the developer. This allows fixing problems on the spot without waiting for a dump and post-analysis.

According to WWDC 2022, Leaks can detect even complex multi-level retain cycles — for example, when three or more objects form a closed chain of strong references. For diagnosing such cycles, the Cycles & Roots graph is indispensable: it clearly shows how objects reference each other in a loop.

How to Read the Cycles & Roots Graph

Each node in the graph is an object, each arrow is a strong reference. A cycle is a closed loop of arrows. Node color indicates status: red — leaked object, green — root (GC Root), gray — intermediate object. To fix a leak, find an arrow that can be made weak without breaking the logic — and change the reference type in the code.

Energy Log: Energy Consumption Analysis

Energy Log is an Instruments template for measuring application energy consumption. It collects data from the device’s hardware sensors: CPU load, Wi-Fi and cellular radio state, GPS usage, display and Bluetooth. Energy Log shows which operations in the application cause the greatest battery drain and overlays them on a power consumption graph over time.

The tool classifies operations by energy level: low (normal CPU work), medium (Wi-Fi transmission), high (GPS, cellular network, GPU). If Energy Log shows high-level red indicators for an extended period — the app is draining the battery in the background and will be deleted by the user.

Typical problems identified by Energy Log: WakeLock without time limit (the app keeps the CPU active after completing a task), high-accuracy Location Updates in the background (coordinate requests every few seconds), network session anomalies (frequent reconnections to the server). Energy Log recommends logging any such incident and adding a condition to disable the power-intensive operation.

For energy testing, use a real device on battery power — energy consumption readings on the simulator are incorrect. Run Energy Log together with UI tests to automate battery drain checking in CI.

How to Run and Interpret Instruments Results

Launching Instruments is done from Xcode in two ways: through the Product → Profile menu (⌘I) or by opening Instruments as a separate application in Launchpad. The first method is more convenient: Xcode automatically builds the app in profiling mode and runs it on the connected device with the selected template. After stopping the session, Instruments saves the trace to a file with the .trace extension.

Interpreting the results depends on the template. For Time Profiler, look at the Call Tree sorted by Self Weight — the topmost methods are your main bottlenecks. For Allocations — look at # Living after a cyclic scenario: if the object count grew, look for a leak. For Leaks — look at red markers and the Cycles & Roots graph. Compare results before and after optimization — this is the only way to confirm the effectiveness of changes.

// Command line for Instruments in CI
// Integrating Instruments into CI/CD pipeline
import XCTest

class PerformanceTests: XCTestCase {
    func testScrollPerformance() {
        // Measuring collection scroll time
        measure(metrics: [XCTCPUMetric(), XCTMemoryMetric()]) {
            app.scrollToBottom()
        }
    }
}

In CI, you can run Instruments from the command line using xcodebuild -showBuildSettings and xcrun xctrace. This allows automating profiling on every commit and not missing regressions. For analysis, use Baseline comparison: if a metric degrades by 5% relative to the previous commit, the pipeline should stop.

Common mistakes when working with Instruments: profiling on the simulator instead of a device (CPU and GPU data are incorrect), collecting data without a scenario (results are random), ignoring the Call Tree (looking only at the graph, not at specific methods). Fixing these mistakes gives 80% of profiling quality.