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

1. Open instruments.app
2. Look for Time Profiler in the window that is presented to you and open it
3. 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

4. Go back to the Time Profiler window in instruments.app
5. Click All Processes in the UI and select your node process (based on your process pid)
6. Hit the Record button (the red button in the left corner in the Time Profiler UI) to start recording a trace
7. 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)
8. In the Call Tree section of the Time Profiler UI, expand a tree fully (option + right arrow)
9. In the menu bar for instruments.app, click on Instrument -> Export track for 'Time Profiler - node'... and save the csv file
10. Goto the flamegraph app by thlorenz.
11. 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

12. 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

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

Happy debuggin'!