# perf-sym

Translate symbol names generated by `--basic-perf-prof` into JavaScript names.
__You can use this tool to generate Flamegraphs on OSX and Linux__.

## Install

```sh
[sudo] npm i -g perf-sym stackvis
```

## Usage

```
  cat stacks.out | perf-sym <pid>

  --relative=[path] -r=[path] [false]
  --keep-addr -k [false]
```


## Generate a flamegraph

### Instrument your code

Your process needs to shut down properly to generate the symbol map, so
instrument it with:

```js
console.error('process.pid', process.pid)

// Cleanly shut down process on SIGINT to ensure that perf-<pid>.map gets flushed
process.on('SIGINT', onSIGINT)

function onSIGINT () {
  // IMPORTANT to log on stderr, to not clutter stdout which is purely for data, i.e. dtrace stacks
  console.error('Caught SIGINT, shutting down.')

  // close any servers you have opened
  server.close()

  // clean exit
  process.exit(0)
}
```

### OS X

#### Requirements

Run your application, in one terminal:

```
node --perf-basic-prof index.js
# this should emit the PID of the process to stdout
```

In another terminal, run:

```
sudo profile_1ms.d -p YOURPID  > stacks.out
```

In another terminal, run a load/soak test:

```
wrk -c 100 -d 10 http://localhost:3000
```

When the load/soak test is finished, hit `CTRL-C` in the terminal running
your application.

now run:

```
cat stacks.out | perf-sym YOURPID | stackvis perf > flamegraph.html
open flamegraph.html
```

### Linux

#### Requirements

Run your application, in one terminal:

```
node --perf-basic-prof index.js
# this should emit the PID of the process to stdout
```

In another terminal, run:
```
perf record -p YOURPID -i -g -e cycles:u; perf script > stacks.out
```

In another terminal, run a load/soak test:

```
wrk -c 100 -d 10 http://localhost:3000
```

When the load/soak test is finished, hit `CRL-C` in the terminal running
your application.

now run:

```
cat stacks.out | perf-sym YOURPID | stackvis perf > flamegraph.html

open flamegraph.html
```

## Contributors

* David Mark Clements
* Matteo Collina

## Acknowledgements

* sponsored by nearForm
* with thanks to [thlorenz](https://github.com/thlorenz) and his [cpuprofilify](https://github.com/thlorenz/cpuprofilify) module for inspiration and snippets and profile_1ms.d

## License

MIT