zeusdeux/Flamegraph_osx.md

Last active February 14, 2025 20:23

Star (29) You must be signed in to star a gist
Fork (0) You must be signed in to fork a gist

Learn more about clone URLs
Clone this repository at <script src="https://gist.github.com/zeusdeux/aac6f8500917319213c5.js"></script>
Save zeusdeux/aac6f8500917319213c5 to your computer and use it in GitHub Desktop.

Download ZIP

Node.js flamegraphs on osx using instruments.app, node and http://thlorenz.github.io/flamegraph/web/

Raw

Flamegraph_osx.md

Flamegraphs for your node processes on OS X

This document will help you generate flamegraphs for your node processes on OS X.

You can read about the various types of flamegraphs and how they are useful
in Brendan Gregg's wonderful write up here.

By the end of this document, you should have a flamegraph for you node app to play with.

Let's get started.

Pre-requisites

Install Xcode from the App Store if you don't have it already
- In this exercise, we need Xcode mainly so that we can use the instruments.app that comes packaged with it. Though it is quite a joy to have when you're trying to bridge C/C++ code with js land (see lldb-jbt)
Install node (version > 0.11.x). Distributions can be found here

Steps

Open instruments.app
Look for Time Profiler in the window that is presented to you and open it
Run your node process with the --perf-basic-prof flag. This flag tells v8 to generate a perf-<pid>.map file (in /tmp/ by default) which can be consumed by the perf tool on *nix systems. You can read more here

Example node --perf-basic-prof app.js
- It's a good idea to print the process.pid in app.js as we'll be using it later
  - console.log(process.pid) should suffice

Go back to the Time Profiler window in instruments.app
Click All Processes in the UI and select your node process (based on your process pid)
Hit the Record button (the red button in the left corner in the Time Profiler UI) to start recording a trace
Click Stop when you've a large enough sample to work with (this is completely subjective as it depends on what you're actually looking for)
In the Call Tree section of the Time Profiler UI, expand a tree fully (option + right arrow)
In the menu bar for instruments.app, click on Instrument -> Export track for 'Time Profiler - node'... and save the csv file
Goto the flamegraph app by thlorenz.
Upload you csv you saved in step 9 as the file for Callgraph

You should see a flamegraph appear with hex memory addresses. The next step will make those addresses take on human readable names

Upload the map file as the file for Mapfile

To get to the map file, do the following
- Click choose file in the flamegraph web app UI
- In the file dialog that opens up, press cmd + shift + g
- Type /tmp in the dialog that pops up and hit Go
- In the folder that opens up, select perf-<your node process pid>.map and click Open

Aaand we're done. The svg file should now have human readable symbols in place of hex memory addresses.

Happy debuggin'!

thlorenz commented Jan 4, 2015

Actually there is a faster way to launch instruments if you got a local Node.js copy.
Load it into Xcode, set your args in Run tab and configure Profiling tab.

Then simply press CMD-I in order to start profiling with Instruments. That's faster than attaching to process every time and the preferred way if you do this repeatedly.
That also allows you to quickly patch v8 in order to ensure that perf-<pid>.map file gets flushed continuously.

I'm pretty sure I used the other technique in this talk and it quickly becomes obvious how annoying it is to attach repeatedly.

Author

zeusdeux commented Jan 4, 2015

Afaik, most node devs don't have a local copy of the source (most nvm it), let alone an Xcode project for node which is why I went with these instructions.

Nevertheless, I shall add the Xcode project method too for the veterans out there. Mainly for v8 patch trick to flush the mapfile continuously (atleast when I am debugging).

Do you have some docs on how to generate an Xcode project directly (will need to add this bit too) instead instantiating an empty one and then adding node src etc? If I am not wrong, there's something that I can pass to ./configure I think. Do not remember.

And yeah, I remember this method from that very talk haha. Also, I might know why the demo didn't work at the end 😜.

thlorenz commented Jan 4, 2015

Here is a script to just paste into the terminal to create Xcode project, pretty simple actually.
To just create the Xcode project without building you can omit the make step.

Author

zeusdeux commented Jan 4, 2015

Awesome, let me add that in.

Author

zeusdeux commented Jan 4, 2015

The Run tab and Profiling tab are the ones under Edit Scheme right?
What are the arguments that you provide under Profiling and Run?
For Run I am going to guess its node --perf-basic-prof app.js, but Profiling I am blank.

ChuntaoLu commented Aug 24, 2015

It's worth noting that --perf-basic-prof flag requires node version at least v0.11

bringingkatigbak commented Mar 2, 2016

Also worth noting that in order for the perf-.map to actually work I had to add the following line to my main file (server.js)
process.on('SIGINT',function(){server.close(); process.exit(0);});

HTH!

also, I used the forked version of flamegraphs that supports the -m flag