Instruments Flame Graph Introduction
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?
I’m writing a book 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 get updates on the book’s progress at the following link: