damage
Version:
A simple way to calculate the 'damage' of running a task in Node.JS.
246 lines (209 loc) • 8.43 kB
HTML
<html><head><meta charset="utf-8"><style>html { font-size: 100%; overflow-y: scroll; -webkit-text-size-adjust: 100%; -ms-text-size-adjust: 100%; }
body{
color:#444;
font-family:Georgia, Palatino, 'Palatino Linotype', Times, 'Times New Roman',
"Hiragino Sans GB", "STXihei", "微软雅黑", serif;
font-size:12px;
line-height:1.5em;
background:#fefefe;
width: 45em;
margin: 10px auto;
padding: 1em;
outline: 1300px solid #FAFAFA;
}
a{ color: #0645ad; text-decoration:none;}
a:visited{ color: #0b0080; }
a:hover{ color: #06e; }
a:active{ color:#faa700; }
a:focus{ outline: thin dotted; }
a:hover, a:active{ outline: 0; }
span.backtick {
border:1px solid #EAEAEA;
border-radius:3px;
background:#F8F8F8;
padding:0 3px 0 3px;
}
::-moz-selection{background:rgba(255,255,0,0.3);color:#000}
::selection{background:rgba(255,255,0,0.3);color:#000}
a::-moz-selection{background:rgba(255,255,0,0.3);color:#0645ad}
a::selection{background:rgba(255,255,0,0.3);color:#0645ad}
p{
margin:1em 0;
}
img{
max-width:100%;
}
h1,h2,h3,h4,h5,h6{
font-weight:normal;
color:#111;
line-height:1em;
}
h4,h5,h6{ font-weight: bold; }
h1{ font-size:2.5em; }
h2{ font-size:2em; border-bottom:1px solid silver; padding-bottom: 5px; }
h3{ font-size:1.5em; }
h4{ font-size:1.2em; }
h5{ font-size:1em; }
h6{ font-size:0.9em; }
blockquote{
color:#666666;
margin:0;
padding-left: 3em;
border-left: 0.5em #EEE solid;
}
hr { display: block; height: 2px; border: 0; border-top: 1px solid #aaa;border-bottom: 1px solid #eee; margin: 1em 0; padding: 0; }
pre , code, kbd, samp {
color: #000;
font-family: monospace;
font-size: 0.88em;
border-radius:3px;
background-color: #F8F8F8;
border: 1px solid #CCC;
}
pre { white-space: pre; white-space: pre-wrap; word-wrap: break-word; padding: 5px 12px;}
pre code { border: 0px ; padding: 0;}
code { padding: 0 3px 0 3px; }
b, strong { font-weight: bold; }
dfn { font-style: italic; }
ins { background: #ff9; color: #000; text-decoration: none; }
mark { background: #ff0; color: #000; font-style: italic; font-weight: bold; }
sub, sup { font-size: 75%; line-height: 0; position: relative; vertical-align: baseline; }
sup { top: -0.5em; }
sub { bottom: -0.25em; }
ul, ol { margin: 1em 0; padding: 0 0 0 2em; }
li p:last-child { margin:0 }
dd { margin: 0 0 0 2em; }
img { border: 0; -ms-interpolation-mode: bicubic; vertical-align: middle; }
table { border-collapse: collapse; border-spacing: 0; }
td { vertical-align: top; }
@media only screen and (min-width: 480px) {
body{font-size:14px;}
}
@media only screen and (min-width: 768px) {
body{font-size:16px;}
}
@media print {
* { background: transparent ; color: black ; filter:none ; -ms-filter: none ; }
body{font-size:12pt; max-width:100%; outline:none;}
a, a:visited { text-decoration: underline; }
hr { height: 1px; border:0; border-bottom:1px solid black; }
a[href]:after { content: " (" attr(href) ")"; }
abbr[title]:after { content: " (" attr(title) ")"; }
.ir a:after, a[href^="javascript:"]:after, a[href^="#"]:after { content: ""; }
pre, blockquote { border: 1px solid #999; padding-right: 1em; page-break-inside: avoid; }
tr, img { page-break-inside: avoid; }
img { max-width: 100% ; }
@page :left { margin: 15mm 20mm 15mm 10mm; }
@page :right { margin: 15mm 10mm 15mm 20mm; }
p, h2, h3 { orphans: 3; widows: 3; }
h2, h3 { page-break-after: avoid; }
}
</style><title>README</title></head><body><h1 id="damage">Damage</h1>
<h4 id="find-out-what-is-killing-your-nodejs-process">Find out what is killing your Node.JS process.</h4>
<p>A simple way to profile the damage of running a task in a Node.JS instance.</p>
<h2 id="how-it-works">How it works</h2>
<p>When you request a new damage calculation it follow these steps:</p>
<ul>
<li>Creates a script prepared to handle the test.</li>
<li>Fork it.</li>
<li>Execute it gathering process information.</li>
<li>Process the result.</li>
<li>Print/emit the result.</li>
</ul>
<h2 id="quick-start">Quick start</h2>
<h3 id="installing">Installing</h3>
<p>With <strong>Node.JS</strong> and <strong>NPM</strong> installed, type:</p>
<pre><code>$ npm install damage
</code></pre>
<h3 id="configuring-the-damage">Configuring the damage</h3>
<p>Use this to get the Damage constructor.</p>
<pre><code class="js">var Damage = require('damage');
</code></pre>
<p>Then you can use <code>prepare()</code> to define a <code>preparation task</code> to run before each collection of tasks.</p>
<pre><code class="js">Damage.prepare(function () {
var fs = require('fs');
});
</code></pre>
<p>Then finally you can just get your <code>damageOf()</code> function, that you need to create damage tests.</p>
<pre><code class="js">var damageOf = Damage();
</code></pre>
<p>Now that you have the function, just use it with a <code>description</code>, a <code>damage test function</code> and the <code>number of damage repeats</code>, just like this:</p>
<pre><code class="js">
damageOf('reading a file',function () {
fs.readFileSync(__filename);
done();
},1000);
</code></pre>
<p><strong>Remember: Inside the test function you need to call <code>done()</code> after you finish the task.</strong></p>
<h4 id="result-of-that-damage">Result of that damage</h4>
<p><img alt="" src="https://dl.dropboxusercontent.com/u/21773527/damage-result.jpg" /></p>
<h2 id="features">Features</h2>
<h3 id="configuration">Configuration</h3>
<p>You can change the global configuration of Damage with this:</p>
<pre><code class="js">Damage.config({
colors: false
});
</code></pre>
<p>To see all Damage's configuration, read this <a href="https://github.com/pedronasser/damage/blob/master/lib/config.js">configuration file</a>.</p>
<h3 id="environment">Environment</h3>
<p>You can change the Damage environment object with this:</p>
<pre><code class="js">Damage.env({
shit: true
});
</code></pre>
<p>Then when you can access env variables like this:</p>
<pre><code class="js">var damageOf = Damage();
damageOf('testing some stuff', function () {
if (env.shit)
// do stuff
else
// do stuff
},1000);
</code></pre>
<h3 id="preparation-script">Preparation Script</h3>
<p>You can change the Damage environment object with this:</p>
<pre><code class="js">Damage.prepare(function () {
var fs = require('fs');
var _ = require('underscore');
var mongoose = require('mongoose');
});
</code></pre>
<h3 id="defining-where-test-begins">Defining where test begins</h3>
<p>Some cases you'll need to do specific task that can not be placed inside <code>prepare()</code> becuse is not used in other tasks.
For those cases you can use <code>start()</code> to define where the test really begins. </p>
<p>Just like this:</p>
<pre><code class="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);
...
</code></pre>
<p>Add the <code>start()</code> to define that test will start now.</p>
<pre><code class="js"> ...
start();
...
</code></pre>
<p>Now the real test begins.</p>
<pre><code class="js"> ...
for (o in obj)
obj[o]=Number(obj[o]).valueOf();
done(); // And stops here.
},1000);
</code></pre>
<h3 id="inspecting-the-result">Inspecting the result</h3>
<p>You can listen for the final processed and full result of each damage test using this:</p>
<pre><code class="js">// Add this after the damageOf() call
.is(function (processed,result) {
fs.writeFile('output.log',JSON.parse(processed));
})
</code></pre>
<h3 id="dumping-memory-heap">Dumping memory heap</h3>
<p>Now you can get a heap snapshot file for each task. Just define the following configurations:</p>
<pre><code class="js">Damage.config({
heapdump: true,
dumpPath: __dirname+'/tmp/' // Where you want to save all heap snapshots.
});
</code></pre>
<h2 id="examples">Examples</h2>
<p>There are some examples <a href="https://github.com/pedronasser/damage/blob/master/examples/">here</a>. =)</p></body></html>