04 Lab 3 Profiling and Documentation.md

# Profiling and Documentation

Resources:

1. [Lecture slides](https://drive.google.com/open?id=1takMoPNZTk4IyfqrEssDm9yFfkQQxuA16ZBoohUso80)

## 1 Profiling

NodeJS includes the **Tick Profiler**, a native tool, which allows you to profile your NodeJS code. It is activated using the `--prof` flag, eg:

```shell
$ node --prof index.js
```

This will capture data on the performance but, in a development environment this will need to be simulated using the [Apache Bench](https://httpd.apache.org/docs/2.4/programs/ab.html) tool, eg:

```shell
$ ab -k -c 20 -n 250 "http://localhost:8080"
```

You will note that there are three flags used:

1. `-k` - **KeepAlive** - perform multiple requests using the same session.
2. `-c 20` - **Concurrency**: the number of concurrent requests.
3. `-n 250` - **Requests**: the number of requests to perform in the session.

Apache Bench generates a range of useful data however we need more information to highlight where the issues are in the code. This is done using a _tick file_.

## The Tick File

by using the `--prof` flag, NodeJS generates a _tick file_ in the current directory with the name `isolate-0xnnnnnnnnnnnn-v8.log`, where nnn... is a number. This file needs to be interpreted using a _tick interpreter_ and the analysis piped to a text file which can then be opened and read.

```shell
$ node -prof-process  isolate-0xnnnnnnnnnnnn-v8.log > processes.txt
```

## References

https://nodejs.org/en/docs/guides/simple-profiling/

Using the profiling tool together with the [Apache Bench](https://httpd.apache.org/docs/2.4/programs/ab.html) server benchmarking tool.

## 2 Debugging

Node.js includes an out-of-process debugging utility accessible via a V8 Inspector and built-in debugging client. To use it, start Node.js with the inspect argument followed by the path to the script to debug; a prompt will be displayed indicating successful launch of the debugger:

```shell
$ node inspect index.js
  < Debugger listening on ws://127.0.0.1:9229/ea2bbf59-874e-45c0-9535-1553980dfec2
  < For help, see: https://nodejs.org/en/docs/inspector
  < Debugger attached.
```

By default the debugger will stop on the first statement. It supports several commands:

| cmd | action                                                                              |
| :-: | ----------------------------------------------------------------------------------- |
| n   | Step next (run the highlighted line and move to the next line but don't execute it) |
| s   | Step in  |
| o   | Step out |
| c   | Continue execution until next breakpoint |

It is also possible to attach watchers to track values:

- `watch(expr)` - Add expression to watch list
- `unwatch(expr)` - Remove expression from watch list
- `watchers` - List all watchers and their values (automatically listed on each breakpoint)

### Using the Chrome DevTools

The debugger can also connect to the Chrome Devtools.

Open the `about:inspect` url in the chrome browser, this will open the devtools window as shown. Click on the 

![opening the Chrome DevTools](exercises/.images/devtools1.png)

This will start monitoring websockets on two ports, we will be using port `9229`.

![opening the Chrome DevTools](exercises/.images/devtools2.png)

Start your script as before using the `node inspect index.js` command.

## 3 Documentation

### 3.1 JSDoc

### 3.2 APIDoc