Post-Mortem Diagnostics & How To Debug Node.js?
Post-Mortem Diagnostics & How To Debug Node.js?

Post-mortem diagnostics & debug Node.js comes into the picture when you want to figure out what went wrong with your Node.js application in production.

In this chapter of Node.js at Scale we will take a look at node-report, a core project which aims to help you to do post-mortem diagnostics & debugging.

The node-report diagnostics module

The purpose of the module is to produce a human-readable diagnostics summary file. It is meant to be used in both development and production environments.

The generated report includes:

  • JavaScript and native stack traces,
  • heap statistics,
  • system information,
  • resource usage,
  • loaded libraries.

Currently node-report supports Node.js v4, v6, and v7 on AIX, Linux, MacOS, SmartOS, and Windows.

Adding it to your project just takes an npm install and require:

Once you add node-report to your application, it will automatically listen on unhandled exceptions and fatal error events, and will trigger a report generation. Report generation can also be triggered by sending a USR2 signal to the Node.js process.

Use cases of node-report

Diagnostics of exceptions

For the sake of simplicity, imagine you have the following endpoint in one of your applications:

This code simply throws an exception once the /exception route handler is called. To make sure we get the diagnostics information, we have to add the node-report module to our application, as shown previously.

Let’s see what happens once the endpoint gets called! Our report just got written into a file:

The header

Once you open the file, you’ll get something like this:

You can think of this part as a header for your diagnostics summary – it includes..

  • the main event why the report was created,
  • how the Node.js application was started (node demo/exception.js),
  • what Node.js version was used,
  • the host operating system,
  • and the version of node-report itself.

The stack traces

The next part of the report includes the captured stack traces, both for JavaScript and the native part:

In the JavaScript part, you can see..

  • the stack trace (which function called which one with line numbers),
  • and where the exception occurred.

In the native part, you can see the same thing – just on a lower level, in the native code of Node.js

Heap and garbage collector metrics

You can see in the heap metrics how each heap space performed during the creation of the report:

  • new space,
  • old space,
  • code space,
  • map space,
  • large object space.

These metrics include:

  • memory size,
  • committed memory size,
  • capacity,
  • used size,
  • available size.

Resource usage

The resource usage section includes metrics on..

  • CPU usage,
  • the size of the resident set size,
  • information on page faults,
  • and the file system activity.

System information

The system information section includes..

  • environment variables,
  • resource limits (like open files, CPU time or max memory size)
  • and loaded libraries.

Diagnostics of fatal errors

The node-report module can also help once you have a fatal error, like your application runs out of memory.

By default, you will get an error message something like this:

On its own, this information is not that helpful. You don’t know the context, or what was the state of the application. With node-report, it gets better.

First of all, in the generated post-mortem diagnostics summary you will have a more descriptive event:

Secondly, you will get the native stack trace – that can help you to understand better why the allocation failed.

Diagnostics of blocking operations

Imagine you have the following loops which block your event loop. This is a performance nightmare.

With node-report you can request reports even when your process is busy, by sending the USR2 signal. Once you do that you will receive the stack trace, and you will see in a minute where your application spends time.

(Examples are taken for the node-report repository)

The API of node-report

Triggering report generation programmatically

The creation of the report can also be triggered using the JavaScript API. This way your report will be saved in a file, just like when it was triggered automatically.

Getting the report as a string

Using the JavaScript API, the report can also be retrieved as a string.

Using without automatic triggering

If you don’t want to use automatic triggers (like the fatal error or the uncaught exception) you can opt-out of them by requiring the API itself – also, the file name can be specified as well:


If you feel like making Node.js even better, please comment down below
Don’t forget to subscribe to our blog.
And If you like this article, then please share it and help us grow.
Thank you for reading.

☞ Node Js Projects

☞ Node.js For Beginners

☞ A Simple Node.js/Mongo/Restify API in Less Than 3 Hours

☞ Typescript Async/Await in Node JS with testing


  1. On the contrary, business signage doesn’t force any person to look at it and yet they get noticed at the most appropriate time when someone walks or drives past it. Most coaching programs provide you with the opportunity to asses yourself and this can be very helpful.Admit it, it is hard to capture the attention of prospective customers these days, due to prevalence of tight competition. A laser beam beyond just the ach and every thin and this allows the scanner for additional details on study barcodes at longer term distances. These include interior and exterior decorating, commercial coatings, commercial paint spraying, painting of timber and woodwork, and painting inside the offices efficiently.

  2. Suggestions For People Who Are Interested In RenovationVirtually people have a minumum of one point they would like to see modified regarding home. More so, the ones that are using Macintosh OS X always find it too difficult when it comes to traveling abroad with their mobile device. During this period, the seed loses most of the moisture that had. To do this, there must be a process of prior hydrolysis and mobilization to generate small molecules that can be used by the developing seedling. You also may study clientcoach relationships as well as professional ethics.


Please enter your comment!
Please enter your name here