Node.js process.report API for Diagnosing Crashes

This article explains the purpose and utility of the process.report API in Node.js, a built-in diagnostic tool designed to help developers identify and troubleshoot runtime crashes, memory leaks, and performance anomalies. It covers what information these reports contain, why they are essential for post-mortem analysis, and how to trigger them both programmatically and automatically.

What is the process.report API?

The process.report API is a native Node.js feature that generates a comprehensive, JSON-formatted diagnostic report upon request or when specific triggers occur. This report captures a detailed snapshot of the application’s state and the hosting environment at a specific point in time, making it an invaluable tool for debugging complex production issues.

Unlike traditional logs, which may only show an error message and a partial stack trace, a diagnostic report provides a holistic view of the system’s health without requiring external monitoring tools or heavy debugging configurations.

The Purpose of process.report in Diagnosing Crashes

The primary purpose of the process.report API is to simplify post-mortem analysis. When a Node.js application crashes unexpectedly, crucial runtime data is typically lost. The diagnostic report bridges this gap by capturing the following critical information:

• Stack Traces: Both JavaScript and native C/C++ call stacks, allowing developers to see exactly what execution path led to the crash.
• Heap Statistics: Detailed memory usage data, including heap size, heap limit, and metadata about V8 heap spaces, which helps diagnose Out-of-Memory (OOM) errors.
• System Information: Information about the operating system, CPU architecture, platform, and resource limits (ulimits).
• Environment Variables: A list of the environment variables active when the report was generated.
• Resource Usage: Data regarding active libuv handles, open file descriptors, and network connections.

How to Trigger Diagnostic Reports

Node.js allows you to generate these reports either automatically based on specific process events or programmatically within your code.

1. Automatic Triggers via Command-Line Flags

You can configure Node.js to generate a report automatically when critical events occur by using command-line flags during startup:

• --report-on-fatalerror: Generates a report when an unrecoverable error (like an Out-of-Memory event) crashes the V8 engine.
• --report-uncaught-exception: Generates a report when an uncaught JavaScript exception occurs.
• --report-on-signal: Generates a report when the process receives a specific operating system signal (such as SIGUSR2).

Example usage:

node --report-on-fatalerror --report-uncaught-exception app.js

2. Programmatic Triggering

If you want to capture the application state during a specific edge case or caught error, you can trigger the report directly in your code using the API:

try {
  // Code that might fail
} catch (error) {
  console.error('An error occurred. Generating diagnostic report...');
  process.report.writeReport();
}

By default, the report is written to a file in the current working directory with a filename containing a timestamp and the process ID, though the destination directory and filename can be customized using configuration options.