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'!

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