README

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.

var Damage = require('damage');

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

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

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

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:


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

Features

Configuration

You can change the global configuration of Damage with this:

Damage.config({
    colors: false
});

To see all Damage's configuration, read this configuration file.

Environment

You can change the Damage environment object with this:

Damage.env({
    shit: true
});

Then when you can access env variables like this:

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:

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:

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.

    ...
    start();
    ...

Now the real test begins.

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

// 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:

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

Examples

There are some examples here. =)