Diagnostic Reports in Node.js

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.