Repository files navigation

node-memwatch is here to help you detect and find memory leaks inNode.JS code. It provides:

• Aleak event, emitted when it appears your code is leaking memory.

• Astats event, emitted occasionally, giving youdata describing your heap usage and trends over time.

• AHeapDiff class that lets you compare the state of your heap betweentwo points in time, telling you what has been allocated, and whathas been released.

• npm install memwatch-next

or

• git clone git://github.com/marcominetti/node-memwatch.git

There are a growing number of tools for debugging and profiling memoryusage in Node.JS applications, but there is still a need for aplatform-independent native module that requires no specialinstrumentation. This module attempts to satisfy that need.

To get started, importnode-memwatch like so:

varmemwatch=require('memwatch-next');

You can then subscribe toleak events. Aleak event will beemitted when your heap usage has increased for five consecutivegarbage collections:

memwatch.on('leak',function(info){ ...});

Theinfo object will look something like:

{start:Fri,29Jun201214:12:13GMT,end:Fri,29Jun201214:12:33GMT,growth:67984,reason:'heap growth over 5 consecutive GCs (20s) - 11.67 mb/hr'}

The best way to evaluate your memory footprint is to look at heapusage right aver V8 performs garbage collection.memwatch doesexactly this - it checks heap usage only after GC to give you a stablebaseline of your actual memory usage.

When V8 performs a garbage collection (technically, we're talkingabout a full GC with heap compaction),memwatch will emit astatsevent.

memwatch.on('stats',function(stats){ ...});

Thestats data will look something like this:

{"num_full_gc":17,"num_inc_gc":8,"heap_compactions":8,"estimated_base":2592568,"current_base":2592568,"min":2499912,"max":2592568,"usage_trend":0}

estimated_base andusage_trend are tracked over time. If usagetrend is consistently positive, it indicates that your base heap sizeis continuously growing and you might have a leak.

V8 has its own idea of when it's best to perform a GC, and under aheavy load, it may defer this action for some time. To aid inspeedier debugging,memwatch provides agc() method to force V8 todo a full GC and heap compaction.

So far we have seen howmemwatch can aid in leak detection. Forleak isolation, it provides aHeapDiff class that takes two snapshotsand computes a diff between them. For example:

// Take first snapshotvarhd=newmemwatch.HeapDiff();// do some things ...// Take the second snapshot and compute the diffvardiff=hd.end();

The contents ofdiff will look something like:

{"before":{"nodes":11625,"size_bytes":1869904,"size":"1.78 mb"},"after":{"nodes":21435,"size_bytes":2119136,"size":"2.02 mb"},"change":{"size_bytes":249232,"size":"243.39 kb","freed_nodes":197,"allocated_nodes":10007,"details":[{"what":"String","size_bytes":-2120,"size":"-2.07 kb","+":3,"-":62},{"what":"Array","size_bytes":66687,"size":"65.13 kb","+":4,"-":78},{"what":"LeakingClass","size_bytes":239952,"size":"234.33 kb","+":9998,"-":0}]}}

The diff shows that during the sample period, the total number ofallocatedString andArray classes decreased, butLeaking Classgrew by 9998 allocations. Hmmm.

You can useHeapDiff in youron('stats') callback; even though ittakes a memory snapshot, which triggers a V8 GC, it will not triggerthestats event itself. Because that would be silly.

Please see the Issues to share suggestions and contribute!

http://wtfpl.org