How To Capture Node.js Garbage Collection Traces

Garbage collection (GC) is a fundamental aspect of memory management in Node.js applications. However, inefficient garbage collection can lead to performance issues, causing application slowdowns and potentially impacting user experience. To ensure optimal performance and diagnose memory problems, it’s essential to study garbage collection traces. In this blog post, we’ll explore various methods for capturing garbage collection traces from Node.js applications.

Options To Capture Garbage Collection Traces From Node.js Applications

There are 3 options to capture Garbage Collection traces from the Node.js applications:

1. –trace-gc flag
2. v8 module
3. Performance hook

Let’s discuss them in this post.

1. –trace-gc Flag

The easiest and most straightforward approach is to pass the –trace-gc flag along with your usual invocation command. For example:

node --trace-gc my-script.mjs

Once the –trace-gc flag is enabled, your Node.js application will start generating garbage collection traces in the console output. These traces provide valuable insights into memory usage, GC events, and potential performance bottlenecks. Garbage collection traces would look something like this:

[721159:0x61f0210]  1201125 ms: Scavenge 27.7 (28.8) -> 26.8 (29.8) MB, 0.5 / 0.2 ms  (average mu = 
0.999, current mu = 0.970) allocation failure 
[721166:0x5889210]  1201338 ms: Scavenge 30.7 (32.1) -> 29.7 (33.1) MB, 0.6 / 0.3 ms  (average mu = 
0.998, current mu = 0.972) allocation failure 
[721173:0x54fc210]  1202608 ms: Scavenge 26.8 (28.3) -> 25.8 (29.3) MB, 0.7 / 0.4 ms  (average mu = 
0.999, current mu = 0.972) allocation failure 
[721152:0x54ca210]  1202879 ms: Scavenge 30.5 (31.8) -> 29.6 (32.8) MB, 0.6 / 0.2 ms  (average mu = 
0.999, current mu = 0.978) allocation failure 
[721166:0x5889210]  1202925 ms: Scavenge 30.6 (32.1) -> 29.7 (33.1) MB, 0.7 / 0.3 ms  (average mu = 
0.998, current mu = 0.972) task 
[721159:0x61f0210]  1203105 ms: Scavenge 27.7 (28.8) -> 26.7 (29.8) MB, 0.4 / 0.2 ms  (average mu = 
0.999, current mu = 0.970) allocation failure 
[721173:0x54fc210]  1204660 ms: Scavenge 26.8 (28.3) -> 25.8 (29.3) MB, 0.5 / 0.2 ms  (average mu = 
0.999, current mu = 0.972) allocation failure

2. v8 Module

If you don’t want to enable GC traces for the entire lifetime of the application or if you want to enable them only on certain conditions or in certain parts of code, then you can use the v8 module, as it provides options to add/remove flags at run-time. Using the v8 module, you can pass the –trace-gc flag and remove it as shown in the code snippet below:

import v8 from 'v8'; 
// enable trace-gc 
v8.setFlagsFromString('--trace-gc'); 
// app code 
// .. 
// .. 

// disable trace-gc 
v8.setFlagsFromString('--notrace-gc');

3. Performance Hook

Node.js has a built-in perf_hooks module that facilitates you to capture performance metrics from the application. You can use the perf_hooks module to capture garbage collection traces. Refer to the code snippet below:

const { performance, PerformanceObserver } = require('perf_hooks'); 

// Step 1: Create a PerformanceObserver to monitor GC events 
const obs = new PerformanceObserver((list) => {  
   const entries = list.getEntries();  
   for (const entry of entries) {     

    // Printing GC events in the console log    
    console.log(entry);  
   } 
}); 
// Step 2: Subscribe to GC events 
obs.observe({ entryTypes: ['gc'], buffered: true }); 

// Step 3: Stop subscription 
obs.disconnect();

If you notice in the code above, we are doing the following:

1. We are importing the performance and PerformanceObserver classes from the perf_hooks module.
2. We create a PerformanceObserver instance to monitor garbage collection events (gc entry type).
3. Whenever garbage collection events occur in the application, we are logging in to the console using the console.log(entry) statement.
4. We start observing GC events with obs.observe().
5. Finally, we stop observing GC events with obs.disconnect().

When the code snippet above is added to your application, in the console you will start to see the GC events reported in the JSON format as below:

{  
  kind: 'mark_sweep_compact',  
  startTime: 864.659982532,  
  duration: 7.824,  
  entryType: 'gc',  
  name: 'GC Event' 
}
{  
  kind: 'scavenge',  
  startTime: 874.589382193,  
  duration: 3.245,  
  entryType: 'gc',  
  name: 'GC Event' 
}

Conclusion

In this post, we explored three main methods for capturing garbage collection traces in Node.js applications: using the –trace-gc flag, leveraging the v8 module for dynamic tracing, and utilizing the perf_hooks module. Each method offers its own advantages and flexibility in capturing and analyzing GC events. I hope you found it helpful.