LogoفارسیFA

Diagnostic Reports in Node.js

Diagnostic reports in Node.js provide a JSON-formatted snapshot of the runtime state, including JavaScript and native stack traces, heap statistics, platform details, resource usage, and system limits. They are designed for development, testing, and production environments to help identify and resolve issues. Reports can be triggered automatically on uncaught exceptions, fatal errors, and signals, or programmatically via API calls.

process.report.writeReport()process.report.getReport()--report-uncaught-exception / --report-on-fatalerror / --report-on-signal

~2 min read • Updated Dec 30, 2025

1. Introduction


Diagnostic reports capture runtime information when errors occur or when triggered manually. They include details about Node.js internals, system resources, and the execution environment.


2. Report Generation


  • Command-line flags: --report-uncaught-exception, --report-on-fatalerror, --report-on-signal.
  • Signal-based triggering (default: SIGUSR2).
  • Programmatic API: process.report.writeReport() and process.report.getReport().

3. Report Content


  • Header: Event type, timestamp, PID, Node.js version, OS details.
  • JavaScript stack: Captures the error stack trace.
  • Native stack: Low-level C++/V8 stack frames.
  • Heap statistics: V8 memory usage and heap spaces.
  • Resource usage: CPU, memory, page faults, file system activity.
  • libuv handles: Active async, timers, TCP connections, etc.
  • Environment variables: Current process environment.
  • User limits: OS-imposed resource limits.
  • Shared objects: Loaded system libraries.

4. Example


try {
  process.chdir('/non-existent-path');
} catch (err) {
  process.report.writeReport(err);
}

5. Report Versions


  • Version 5: Memory unit values changed to bytes.
  • Version 4: Added ipv4 and ipv6 fields to endpoints.
  • Version 3: Added memory usage keys to resourceUsage.
  • Version 2: Worker thread support.
  • Version 1: Initial release.

6. Configuration


Runtime configuration is available via process.report properties:


  • reportOnFatalError: Trigger on fatal errors.
  • reportOnSignal: Trigger on signals.
  • reportOnUncaughtException: Trigger on uncaught exceptions.
  • signal: Define the signal used for triggering.
  • filename and directory: Control output location.
  • excludeNetwork and excludeEnv: Exclude network or environment data.

7. Worker Thread Integration


Worker threads can generate reports just like the main thread. Reports include information about all child workers, ensuring a complete view of the runtime state.


Conclusion


Diagnostic reports in Node.js are a powerful tool for debugging and monitoring. By capturing detailed runtime information, they help developers analyze failures, optimize performance, and maintain stability in production systems.


Written & researched by Dr. Shahin Siami

Next Article