damage/README.md

A simple way to calculate the 'damage' of running a task in Node.JS.

# Damage

#### Find out what is killing your Node.JS process.
A simple way to profile the damage of running a task in a Node.JS instance.

## How it works

When you request a new damage calculation it follow these steps:

- Creates a script prepared to handle the test.
- Fork it.
- Execute it gathering process information.
- Process the result.
- Print/emit the result.

## Quick start

### Installing

With **Node.JS** and **NPM** installed, type:

    $ npm install damage

### Configuring the damage

Use this to get the Damage constructor.

```js
var Damage = require('damage');
```

Then you can use `prepare()` to define a `preparation task` to run before each collection of tasks.

```js
Damage.prepare(function () {
    var fs = require('fs');
});
```

Then finally you can just get your `damageOf()` function, that you need to create damage tests.

```js
var damageOf = Damage();
```

Now that you have the function, just use it with a `description`, a `damage test function` and the `number of damage repeats`, just like this:

```js

damageOf('reading a file',function () {
  fs.readFileSync(__filename);
  done();
},1000);

```

**Remember: Inside the test function you need to call `done()` after you finish the task.**

#### Result of that damage

![](https://dl.dropboxusercontent.com/u/21773527/damage-result.jpg)

## Features

### Configuration

You can change the global configuration of Damage with this:

```js
Damage.config({
    colors: false
});
```

To see all Damage's configuration, read this [configuration file](https://github.com/pedronasser/damage/blob/master/lib/config.js).

### Environment

You can change the Damage environment object with this:

```js
Damage.env({
    shit: true
});
```

Then when you can access env variables like this:

```js
var damageOf = Damage();
damageOf('testing some stuff', function () {
    if (env.shit)
        // do stuff
    else
        // do stuff
},1000);
```

### Preparation Script

You can change the Damage environment object with this:

```js
Damage.prepare(function () {
    var fs = require('fs');
    var _ = require('underscore');
    var mongoose = require('mongoose');
});
```

### Defining where test begins

Some cases you'll need to do specific task that can not be placed inside `prepare()` becuse is not used in other tasks.
For those cases you can use `start()` to define where the test really begins. 

Just like this:

```js
var damageOf = Damage();
Damage.prepare(function () { var fs = require('fs'); });
damageOf('testing some specific shit', function () {
    var requiredFile = fs.readFileSync('randomfile');
    var obj = JSON.parse(requiredFile);
    ...
```

Add the `start()` to define that test will start now.

```js
    ...
    start();
    ...
```

Now the real test begins.

```js  
    ...  
    for (o in obj)
        obj[o]=Number(obj[o]).valueOf();
        
    done(); // And stops here.
},1000);
```

### Inspecting the result

You can listen for the final processed and full result of each damage test using this:

```js
// Add this after the damageOf() call
.is(function (processed,result) {
  fs.writeFile('output.log',JSON.parse(processed));
})
```

### Dumping memory heap

Now you can get a heap snapshot file for each task. Just define the following configurations:

```js
Damage.config({
    heapdump: true,
    dumpPath: __dirname+'/tmp/' // Where you want to save all heap snapshots.
});
```

## Examples

There are some examples [here](https://github.com/pedronasser/damage/blob/master/examples/). =)