Instruments on Swift Dev Journal

Using Top Functions Mode in Instruments to Quickly Find the Slowest Code

Mon, 10 Aug 2026 13:23:46 -0400

In Xcode 26.4 Apple added a Top Functions mode to the Time Profiler and CPU Profiler instruments to help you quickly find the functions where your app spends the most time. This article explains the Top Functions mode.

If you are new to time profiling with Instruments, read the following article:

Find the Slow Spots in Your Code with the CPU Profiler Instrument

The article covers the CPU Profiler instrument, but the material also applies to the Time Profiler instrument.

Switch to Top Functions Mode

Above the detail view is a set of three buttons.

Click the right button (highlighted in blue in the screenshot) to switch to Top Functions mode.

The Top Functions mode sorts the call tree by the Self Weight column (Self Cycles in the CPU Profiler instrument) so the functions where your app spends the most time appear at the top of the call tree. Double-click a function you wrote to find the lines of code where your app spends the most time.

Flame Graph

Selecting a function from the call tree view shows a flame graph of the code paths that called the function. Focusing on a single function makes the Top Functions flame graph easier to read than reading the complete flame graph.

If you have never used Instruments flame graphs, the following article provides an introduction to them:

Instruments Flame Graph Introduction

Above the flame graph are two buttons. The left button, Callers, shows the default flame graph view. The default view shows the call stack in reverse, with the selected function at the bottom of the graph. The right button, Inverted Callees, inverts the flame graph.

Do you want to learn more about Instruments?

I wrote a book, Profiling Swift Apps, that shows you how to use Instruments to find and fix problems in your code. The book will help you make apps that run faster and use less memory. You can learn more about the book and download a sample at the following link:

Profiling Swift Apps page

Measure App Launch Time with Instruments

Tue, 10 Feb 2026 12:34:53 -0500

Take the following steps to measure your app’s launch time with Instruments:

Press Cmd-I or choose Product > Profile to profile your app.
Select the App Launch template when Instruments launches.
Click the Choose button.
Click the Record button to start profiling.
Select the item with the name of your app from the timeline pane.
Press Cmd-4 to open the App Lifecycle section.

The App Lifecycle section lists the app’s launch steps and how long each step took.

Do you want to learn more about Instruments?

Profiling Swift Apps page

Find the SwiftUI Views that Update the Most Using Instruments

Mon, 03 Nov 2025 12:44:02 -0400

When profiling a SwiftUI app with Instruments, one thing you want to know is what views update the most. If a view updates more than you expect, you want to know what causes the updates. In this article you will learn how to use the SwiftUI instrument to find the views in your app that update the most and find what triggers view updates.

This article uses the new SwiftUI instrument Apple added in Xcode 26. If you are using an earlier version of Xcode, read the following article:

See How Many Times Your SwiftUI Views Redraw Using Instruments

Profile your app

Take the following steps to profile your app with the SwiftUI instrument:

Go to Xcode.
Press Cmd-I or choose Product > Profile to build your project and launch Instruments.
Choose SwiftUI from the template list.
Click the Choose button.
Click the Record button above the sidebar to start profiling.
Click the Stop button when you are finished.

Find the views that update the most

Use the all updates summary to find the views that update the most. Instruments should show the all updates summary when you stop profiling, but if you don’t see it in the detail view, press Cmd-1 or choose Summary: All Updates from the jump bar menu.

The SwiftUI instrument’s all updates summary shows the following statistics for the views in your app:

Number of updates
Total update time
Shortest update
Longest update
Average update time

Take the following steps to find the views that update the most:

Click the disclosure triangle next to the name of your app to see the app’s modules.
Click the disclosure triangle next to your app’s module to see a list of your app’s views.
Click the Count column heading to sort the views by update count so you can see what views update the most.

Find what causes a view to update

Use the cause and effect graph in the SwiftUI instrument to find the cause of view updates. Take the following steps to show the cause and effect graph for a view:

Move the pointer over a view in the all updates summary.
Click the small button that appears next to the name of the view.
Choose Show Cause & Effect Graph.

The cause and effect graph looks similar to the following screenshot:

The graph consists of a collection of nodes with arrows showing the flow of events. Graph nodes for your code are blue. System-defined nodes are gray.

Initially the graph is focused on the view you selected from the summary. The nodes to the left of the view show the events that trigger the view update. The nodes to the right of the view show the effects of the view update.

To figure out what triggers an update, move left along the graph until you find other blue nodes. The most common cause of view updates is data updates. When the data the view shows changes, the view updates.

If you are not seeing any nodes to the left of a particular node, move the pointer over the node to show one or two buttons at the top of the node.

Clicking the left button toggles showing and hiding the nodes to the left of the selected node. If no buttons appear, you reached the end of a path.

Do you want to learn more about the SwiftUI instrument?

I wrote a book, Profiling Swift Apps, that shows you how to use Instruments to find and fix problems in your code. The book has a chapter on using the SwiftUI instrument to find problems in your SwiftUI code. You can learn more about the book and download a sample at the following link:

Profiling Swift Apps page

Find the Slow Spots in Your Code with the CPU Profiler Instrument

Thu, 24 Jul 2025 13:29:07 -0400

If you find your Swift app is running slowly, Instruments includes a CPU Profiler instrument to help you find the code causing your app to run slowly. This article shows you how to use the CPU Profiler instrument to find the slow code in your app.

NOTE

Since I wrote this article, Apple made some changes to the CPU Profiler instrument. Instead of having Weight and Self Weight columns, there are Cyles and Self Cycles columns.

You will have an easier time following this article if you choose the Time Profiler template instead of the CPU Profiler template.

Launching Instruments

In Xcode choose Product > Profile or press Cmd-I to build your Xcode project and launch Instruments.

When Instruments launches a window opens for you to choose a template to profile your app. Select the CPU Profiler template and click the Choose button. If you are running an older version of Xcode that does not have the CPU Profiler template, select the Time Profiler template.

Profiling Your App

Click the Record button at the top of the trace document window or press Cmd-R to start profiling your app. Run your app.

Click the Pause button or press Cmd-Shift-R to pause recording. Click the Stop button or press Cmd-Dot to stop recording.

Reading the Profiling Data

When you stop recording Instruments shows the call tree view.

The call tree view has a listing for each function that executed while profiling.

Finding Your Code in the Call Tree

When you first look at the call tree view, you will see it shows lots of functions that you didn’t write. How do you find your functions in the call tree view?

To find your code in the call tree view, click the Call Tree button at the bottom of the window and click the Hide System Libraries and Invert Call Tree checkboxes.

Hiding the system library code makes it easier to find your app’s functions in the call tree view. Inverting the call tree brings the executed functions to the top of the call tree view.

Finding the Slow Code

How do you know which functions are the slow functions?

Each function in the call tree view has a Weight value and a Self Weight value. The Weight value tells you how long the function was on the call stack. The Self Weight value tells you how long the function was at the top of the call stack.

The Self Weight value is more important. Suppose you have a function A that calls functions X, Y, and Z. The Weight value for A tells you the amount of time your app was in functions A, X, Y, and Z. The Self Weight value for A tells you the amount of time your app was in A. When you’re looking for the slow spots in your code, look at functions with a high Self Weight value.

Clicking the Self Weight column heading sorts the call tree view listings by their Self Weight value. Sorting by Self Weight brings the slow functions to the top of the call tree view.

Viewing the Slow Code

Double-clicking a function in the call tree view opens the source view, where you can see the lines of code that take the most time in the function. Make sure you double-click a function you wrote. If you double-click a function you didn’t write, the source view shows unreadable assembly language code.

Do you want to learn more about Instruments?

Profiling Swift Apps page

Instruments Flame Graph Introduction

Mon, 24 Mar 2025 14:09:38 -0400

Apple added flame graphs to Instruments in Xcode 16 to let developers visualize call tree statistics. Unfortunately Apple did not add much documentation on using flame graphs. I’m writing this article to partially fill the documentation void.

Showing the Flame Graph

You must be in the call tree view to show the flame graph.

There are two buttons on the right side above the detail view. Click the rightmost button to show the flame graph.

If you don’t see the buttons, the instrument does not show flame graphs. Currently only the Time Profiler instrument shows flame graphs. Some time in the future (hopefully soon) all the instruments that have a call tree view will show flame graphs.

Reading the Flame Graph

When you click the button to show the flame graph, the flame graph initially looks similar to the following screenshot:

The flame graph consists of stacks of rectangles. Each rectangle represents a function in your app’s call stack. Looking at the screenshot of the flame graph, you will notice that iOS and Mac apps have a lot of functions. Most of the rectangles are so narrow that you can’t read the function names.

The top of the flame graph shows the function at the bottom of the call stack. This function is most likely the name of your app. Underneath the top rectangle are rectangles for the functions the bottom function called. The stack of rectangles continues downward until you reach the bottom rectangle, which is the function at the top of the call stack.

One area where flame graphs excel is telling you the relative amount of time spent in the functions that a function calls. Suppose you have a function A that calls functions B, C, and D. You can tell whether your app spends more time in B, C, or D by the width of the rectangle. The wider the rectangle, the more time the function was on the call stack.

If you look at the second row in the flame graph screenshot, you will see the start function is on the call stack the most, over 70 percent of the time. The start_wqthread function is on the call stack the second most, around 10 percent. After that are a bunch of other functions whose names you can’t read. The names of the functions and the percentages aren’t important in this case because they involve code I didn’t write. I’m using the second row as an example of reading the flame graph. You have to move farther down the flame graph to find code you wrote.

The functions that spend the most time on the call stack appear on the left side of the graph.

Finding Your Code in the Flame Graph

Functions you wrote have a blue rectangle. You must scroll down the flame graph to find your code because the top of the graph has blue rectangles for functions in your app that you didn’t write, such as main.

The easiest way to find your code is to hide functions in system libraries from the flame graph. Click the Call Tree button at the bottom of the window and select the Hide System Libraries checkbox.

Navigating the Flame Graph

Click a rectangle in the flame graph to select it. After selecting a rectangle, use the arrow keys to navigate the flame graph.

Zooming the Flame Graph

The number of functions in iOS and Mac apps makes it tough to read the function names for most of the flame graph rectangles. How do you zoom the flame graph so you can read those function names?

Create a zoom area. Start by clicking in the flame graph to establish the start of the zoom area. Hold down the Option key, scroll, and release the mouse button to set the zoom area. You can also zoom with a trackpad gesture, but I don’t have a trackpad to test this.

Combine creating a zoom area and hiding system libraries to make your function names readable in the flame graph.

To zoom out, hold down the Option key and click in the graph. Scroll to the top of the flame graph and option-click to zoom out completely.

Summary

The following list has the most important things to remember when reading Instruments flame graphs:

Rectangle width indicates the percentage of time the function was on the call stack.
The functions that spend the most time on the call stack appear on the left side of the graph.
Functions in your app have blue rectangles.
Hide system libraries to focus on your code. Click the Call Tree button at the bottom of the window to hide system libraries.
Option-scroll to zoom the flame graph to read function names.

Acknowledgments

Thanks to James Dempsey and Philippe Casgrain for the information on zooming the flame graph.

Do you want to learn more about Instruments?

Profiling Swift Apps page

See How Many Times Your SwiftUI Views Redraw Using Instruments

Mon, 10 Mar 2025 12:07:02 -0500

If you run into a performance problem in your SwiftUI app, the cause could be your app’s views redrawing too often. Apple provides instruments in the Instruments app that let you see how many times SwiftUI draws your app’s views and the view properties that trigger redraws. This article shows how to use those instruments.

Profile Your App

Take the following steps to profile your app with the SwiftUI instruments:

Go to Xcode.
Press Cmd-I or choose Product > Profile to build your project and launch Instruments.
Choose SwiftUI from the template list.
Click the Choose button.
Click the Record button above the sidebar to start profiling.
Click the Stop button when you are finished.

The SwiftUI template has the following instruments:

View Body
View Properties
Core Animation Commits
Time Profiler
Hangs

I cover the View Body and View Properties instruments in this article. Read the following article to learn more about the Time Profiler instrument:

Finding the Slow Spots in Your Code with the Time Profiler Instrument

See the Number of View Redraws

Use the View Body instrument to see statistics about the redraws of the SwiftUI views in your app. The View Body instrument table has the following columns of data:

Count
Total Duration
Minimum Duration
Average Duration
Maximum Duration
Standard Deviation Duration

The most important columns are Count, Total Duration, and Average Duration. The Count column tells you how many times SwiftUI drew the view. The Total Duration column tells you the total time of those draws. The Average Duration column tells you the average time of each draw.

The View Body instrument table has at least two rows: one for SwiftUI and one for your app. Start by looking at the statistics for your app. You will see the total number of times SwiftUI drew your app’s views.

To see what views were drawn the most, click the disclosure triangle next to your app. There will be a row for each view in your SwiftUI app.

The views that were drawn the most should appear at the top. If you don’t see the views that were drawn the most, click the Count table header to sort the views by count.

See the Properties that Trigger Redraws

If you find one of your views is being redrawn often, you want to figure out what is causing the view to redraw so much. How do you find the cause of redraws?

SwiftUI views redraw when the data bound to the views changes. Use the View Properties instrument to see the properties (variables) that change the most. Anything in your code that uses property wrappers like @State and @Binding will appear in this instrument.

When you select the View Properties instrument, you will see a long list of properties with their current values. You can get more useful information from the summary. Press Cmd-2 or choose Summary from the jump bar to see the summary.

The summary looks similar to the summary for the View Body instrument. There are rows for SwiftUI and your app. There is one column that tells you the number of updates.

Where the View Properties instrument differs is it has levels you can drill down by clicking disclosure triangles. The View Properties instrument has the following levels:

View type
Property type
Property value

The view types for your app are your app’s views. They should be the same as the views in the View Body instrument.

The property types are the data types for the properties in your SwiftUI views. An example of a property type in a SwiftUI view is Binding<String>, which is a binding to a string. The instrument shows the data types, not the names of your variables.

The property values show the different values the property had during profiling. A Boolean property will show the number of times it was set to true and set to false.

You are noticing there’s a lot of disclosure triangle clicking when looking at view properties. Option-clicking a disclosure triangle will expand the list to show all the levels so you don’t have to click as much. Option-clicking again will contract the list.

Do you want to learn more about Instruments?

Profiling Swift Apps page

Finding the Slow Spots in Your Code with the Time Profiler Instrument

Mon, 07 Jan 2019 19:55:55 +0000

I continue my coverage of Instruments with the Time Profiler instrument. If your app is running slowly, use the Time Profiler instrument to find the slow spots in your code so you know where to optimize.

If you are new to Instruments, I recommend reading the Measuring Your App’s Memory Usage with Instruments article. That article provides an introduction to Instruments and covers some aspects of using Instruments this article glosses over.

How the Time Profiler Instrument Works

The Time Profiler instrument records the call stack every millisecond. The function at the top of the call stack is the function your app is currently executing. If a function appears at the top of the call stack in a lot of samples, that’s a sign your app is spending a lot of time in that function.

Launch and Record

Choose Product > Profile in Xcode to launch Instruments. Select the Time Profiler template and click the Choose button.

Click the Record button to launch your app and start profiling.

Controlling the Graph

When you pause recording you’ll notice the Time Profiler instrument shows a lot of graphs. There’s a graph for each thread, and iOS and Mac apps have a surprisingly high number of threads.

Above the graph is a series of buttons to control what graphs appear in the trace document window.

You can show instruments, threads, or CPU cores. You can also use the search field to filter what graphs appear. At the start you should focus on instruments, specifically CPU usage, because it helps find the slow spots in your code.

CPU Usage Graph

Starting with Xcode 10 the Time Profiler instrument has two graphs: CPU usage and life cycle. If you move the mouse cursor over the CPU usage graph, tooltips appear with the percentage of CPU usage at that moment in the recording.

Life Cycle Graph

The life cycle graph reports the current state of your app: initializing, launching, foreground, or background. If you move the mouse over the life cycle graph, tooltips tell you the state of the app and the amount of time the app was in that state.

Older versions of Xcode do not have a life cycle graph.

Profile Data

The Time Profiler instrument shows the call tree view initially. Click the Call Tree button at the bottom of the window and select the Invert Call Tree and Hide System Libraries checkboxes to make your code easier to find in the call tree view.

For each function the call tree tells you its weight and it self weight. The weight is expressed as a time and a percentage. The weight measures the amount of time the function was on the call stack. The self weight measures the amount of time the function was at the top of the call stack.

The Self Weight column is more important. Suppose you have a function A that calls functions B and C. The Weight column for A tells you the amount of time your app was in functions A, B, and C. The Self Weight column for A tells you the amount of time your app was in A. When you’re looking for the slow spots in your code, look at functions with a high self weight.

Double-clicking a function opens the source view, where you can see the lines of code that take the most time in the function.

Narrative

The narrative section has a listing for each event in the Life Cycle graph. Each listing has the start time relative to the start of the recording and a description of what the app is doing.

Older versions of Xcode do not have a narrative section.

Samples

If you choose Samples from the jump bar, you can look at every sample the Time Profiler instrument took during the recording. Instruments shows the following data for each sample:

Sample time, relative to the start of recording
Core, the CPU core
Process, which is the name of your app
Thread
State, which is usually Running
Backtrace, which lists the function at the top of the call stack

The extended detail view shows a compressed backtrace. If you want to see every function in the call stack, click the button at the top right of the backtrace.

Remember that the Time Profiler instrument takes a sample every millisecond so there are a lot of samples to go through.

CPU Cores

If you move the mouse cursor over a CPU core in the graph, a tooltip appears showing you the percentage of CPU usage for that core at that moment in the recording.

Selecting a CPU core from the instrument list fills the detail view with call tree statistics for that core. Choosing Samples from the jump bar shows all the samples Instruments recorded for that CPU core.

Threads

If you move the mouse cursor over a thread in the graph, a tooltip appears showing the percentage of CPU usage for that thread at that moment in the recording. The graph can tell you if the main thread is doing too much work.

Selecting a thread from the instrument list fills the detail view with call tree statistics for that thread. Choosing Samples from the jump bar shows all the samples Instruments recorded for that thread.

Summary

The main point of using the Time Profiler instrument is to find the slow spots in your code. Look for functions in the call tree with a high self weight. If you need to make your app run faster, start by optimizing those functions with a high self weight.

Do you want to learn more about Instruments?

Profiling Swift Apps page

Measuring Your App’s Memory Usage with Instruments

Fri, 14 Dec 2018 05:11:05 +0000

On Stack Overflow I see many questions from people who have trouble interpreting the data Instruments generates. After reading this article you’ll know how to interpret the data Instruments generates for the Allocations and Leaks instruments and learn tips you can use with other instruments.

What is Instruments?

Instruments is an app that is bundled with Xcode to record and display statistics about your app as it runs. Instruments comes with a collection of instruments, each of which records a specific set of statistics. Some popular instruments include the following:

The Leaks instrument checks your app for memory leaks.
The Allocations instrument records statistics about memory allocations.
The Time Profiler instrument measures CPU usage and helps you find the slow spots in your code.

If you’re learning iOS or Mac development, you’re not going to use Instruments at first. You normally use Instruments when you get closer to shipping an app. But if your iOS app is generating memory warnings when you run it or your app runs really slow, you’ll want to profile the app with Instruments.

Launching Instruments

Because Instruments is located inside Xcode’s app bundle, you won’t be able to find it in the Finder. The easiest way to launch Instruments is to profile your project by choosing Product > Profile in Xcode. When Instruments launches, you will be asked to choose a template.

Select the Leaks template and click the Choose button. The Leaks template include both the Leaks and Allocations instruments.

The Trace Document Window

When you click the Choose button, an empty trace document window opens in Instruments.

Running from top to bottom, the main areas of the trace document window are the following:

Toolbar
Instrument list
Jump bar
Detail view
Extended detail view
Bottom bar

For this article the only toolbar items you need to worry about are the buttons to start/stop recording and pause recording on the left side of the toolbar. The toolbar also has controls to choose an app to profile, add an instrument to the trace, and show/hide different parts of the trace document window.

The instrument list shows the instruments being used in the trace along with a graph for each instrument. The graph is going to be empty until you start recording.

The jump bar allows you to choose what to show in the detail view. The detail view shows the profiling statistics. The extended detail view shows additional statistics. For most instruments the extended detail view shows the call stack.

The bottom bar contains controls to filter the information that appears in the detail view.

Configuring an Instrument (Optional)

You won’t need to configure any instruments to follow along with this tutorial. But when you use Instruments, you may need to configure an instrument, and it helps to configure the instrument before you start recording.

Choose File > Recording Options to configure an instrument. The following screenshot shows the configuration options for the Allocations instrument:

Profiling Your App

At this point you can start profiling your app. Click the Record button on the left side of the toolbar. Your app will launch. Use your app. When you are finished, you can either click the Pause button or the Stop button. The Leaks instrument is set to check for leaks every 10 seconds so you should run your app for at least 10 seconds.

If you want to save your trace so you can look at the results later, choose File > Save.

Reading the Profiling Data

Now comes the hard part: making sense of all the data that Instruments generates. Let’s start with the graph. If you move the mouse cursor inside the graph, Instruments shows a tooltip with a piece of data about the graph. The following image shows the memory usage for the Allocations instrument:

You can focus on a specific time interval in the graph by setting an inspection range. Click inside an instrument’s graph and drag to create the inspection range. The inspection range is shaded blue, which you can see in the following screenshot:

When you set an inspection range, the statistics in the detail view change to reflect the time interval in the inspection range. Clicking in the graph outside of the inspection range you set clears the inspection range.

Allocations Instrument Results

Now it’s time to look at data for specific instruments. Let’s start with the Allocations instrument. If you select the Allocations instrument from the instrument list, the detail view shows a summary of the memory allocation data. The most important data is at the top.

To determine how much memory your app is currently using, look at the Persistent Bytes column for the category All Heap Allocations. The text is a little small in the screenshot, but it says the app is using 9.64 MB of memory, which is good for an iOS or Mac app. The Allocations instrument does not record OpenGL/ES or Metal texture memory. If your app allocates texture memory, your actual memory use will be higher than what Instruments reports. You may also want to click the checkbox in the Graph column to show the heap allocation totals in the graph.

The Allocations instrument has the following columns of data for each memory category:

Persistent Bytes, which is the amount of allocated memory that hasn’t been freed yet.
# Persistent, which is the number of memory allocations that haven’t been freed yet.
# Transient, which is the total number of memory allocations that have been freed.
Total Bytes, which is the total amount of allocated memory, including freed memory.
# Total, which is the total number of memory allocations, including freed memory. The # Total column should equal the sum of the # Persistent and # Transient columns.

Suppose your app makes 20 memory allocations of 1,000 bytes and frees the memory for 15 of the allocations. The Allocations instrument would report the following information:

Persistent Bytes: 5,000
# Persistent: 5
# Transient: 15
Total Bytes: 20,000
# Total: 20

Allocations Instrument Call Tree

If your app allocates a high amount of memory, the first thing you’ll want to know is where your code is making the big memory allocations. To find where you’re allocating memory, switch to the call tree view. In the jump bar, click on Statistics and choose Call Trees to switch to the call tree view.

When you switch to the call tree view, you should configure Instruments to make finding your code easier in the call tree view. Click the Call Tree button in the bottom bar to open a popover with a series of checkboxes.

Select the Invert Call Tree and Hide System Libraries checkboxes. Inverting the call tree brings the memory allocating functions to the top. Hiding the system libraries hides Apple’s code, leaving your code in the call tree view.

After selecting the checkboxes, the call tree view should show your code.

Option-clicking a disclosure triangle next to a function in the call tree view expands its subtree so you don’t have to be constantly clicking disclosure triangles. Option-clicking again on the expanded disclosure triangle contracts the subtree.

For each function in the call tree, the Allocations instrument shows the bytes used and the allocation count. The bytes used is represented both as an amount and a percentage of the total memory allocated. Here’s the listing from the Framesetter.init listing:

308.86 KB   1.2%    42

The line says the Framesetter.init function and any functions in its subtree allocated 308.86 KB of memory, which is 1.2% percent of the total allocated memory. This function and any functions in its subtree made 42 allocations.

The subtrees keep Instruments from telling you the exact amount of memory each function allocates. Inverting the call tree reduces the subtree, which makes the listing for a function in an inverted call tree the closest approximation to the amount of memory that function is allocating. If you set an inspection range in the graph, the listing reflects the amount of memory allocated in the inspection range’s time interval.

main Listing

For most Mac and iOS apps, the first listing in the call tree view is the main function. This function is going to have a high amount of bytes used and allocations. If you don’t invert the call tree, the main function will show 100% bytes used. That’s because main is the starting point of your app. Every function in your app will have main in its call stack so every memory allocation your app makes will have main in its call stack.

When trying to figure out where your app allocates memory, don’t worry about the main listing. The main function doesn’t do much in most Mac and iOS apps. There isn’t much you can do in the main function to reduce your app’s memory usage.

Source View

Double-clicking a function in the call tree view shows the source view. For the Allocations instrument, the source view shows you the lines of code that allocated the memory along with the percentage of memory allocated. The percentage is relative to the function. If a line of code says 80%, it means that line of code allocated 80% of the memory the function allocated.

Notice how each listing in the source view has an icon with an exclamation point. Clicking that icon shows the heaviest call stack for that line of code.

Leaks Instrument Results

Now it’s time to look at the Leaks instrument. The graph will tell you if you have any memory leaks in your app. A memory leak occurs when your app allocates memory and never frees the memory. The following screenshot shows an example of the graph for the Leaks instrument:

The screenshot shows six memory leak checks. For the first four checks, Leaks found no memory leaks so it leaves a green icon with a checkmark on the graph. On the fifth check, Leaks found some leaks so it leaves a red icon with an X on the graph. On the last check Leaks found no new leaks so it leaves a gray icon with a dash on the graph.

Leaks Instrument Call Tree

If Instruments finds memory leaks in your app, the next step is to find where the leaks are occurring in your code. The steps to do this are the same as for the Allocations instrument: switch to the call tree view by using the jump bar and select the Invert Call Tree and Hide System Libraries checkboxes from the Call Tree popover in the bottom bar. Selecting the checkboxes will limit the call tree listing to functions you wrote.

For each function in the call tree listing, Instruments shows the bytes used and the number of leaks. Like the Allocations instrument, the bytes used is represented both as an amount and a percentage, but in the Leaks instrument the percentage represents the percentage of total leaked memory. Here’s the listing for the malloc function in the screenshot.

19.12 KB    98.0%   92

The listing says the malloc function has 92 memory leaks totaling 19.12 KB. The leaks totaled 98% of the leaked memory in the app.

Double-click any functions in your call tree view to see where the leaked memory is allocated.

The fact that a function allocates leaked memory doesn’t necessarily mean the function is responsible for leaking the memory. But it’s a good place to start looking for the source of the leak.

Troubleshooting

This section contains fixes for common issues people run into with Instruments.

The Call Tree View Shows Memory Addresses

A problem many people run into when using Instruments is the call tree view shows memory addresses instead of the names of functions. The usual cause of this problem is Instruments being unable to locate the dSYM file that contains the project’s debugging symbols. The function names are in the debugging symbols.

To locate the dSYM file, choose File > Symbols in Instruments. A sheet like the following will open:

Select your app from the left side of the sheet. Click the Locate button to find the dSYM file.

The dSYM file is usually located in the same directory as the app bundle of the release version of your project. The app bundle is in the Derived Data folder. You can check the location of your Derived Data folder in Xcode by choosing File > Project Settings, but the Derived Data folder is usually in the following folder:

/Users/YourUsername/Library/Developer/Xcode/DerivedData

There will be a folder for your project in the Derived Data folder with a long string of random characters after the project name. The release version of the project is in the following folder:

.../DerivedData/ProjectName/Build/Products/Release

An iOS project will have the name Release-iphoneos instead of Release.

The Source View Doesn’t Show Source Code

You double-click a function in the call tree view, expecting to see that function’s code in the source view. But instead you see either assembly language code or a blank view that says Unavailable.

The usual cause of this issue is double-clicking a function you didn’t write. Examples of functions you didn’t write include functions from Apple’s frameworks and default initializers in your structs and classes. Make sure you double-click a function you wrote.

Summary

I want to summarize the most important points to take away from this article. These points apply to most instruments, not just the Leaks and Allocations instruments.

Choose Product > Profile in Xcode to profile your app.
Use the call tree view to find problem areas in your code.
Select the Invert Call Tree and Hide System Libraries checkboxes to find your code in the call tree view.
Option-click the disclosure triangles in the call tree view to minimize the amount of clicking you have to do.
Double-click a function in the call tree view to see statistics on specific lines of code.
Don’t worry about the listing for the main function in the call tree view. You have no control over main.

Do you want to learn more about Instruments?

Profiling Swift Apps page