Does max_memory_restart trigger based on RSS or Heap usage?

Question

PM2 provides the max_memory_restart option to automatically reboot a process when it exceeds a specific memory threshold. This is often used as a safeguard against gradual memory leaks in Node.js applications.

In a production environment using PM2 v5.x, there is uncertainty regarding which specific memory metric the process manager monitors to trigger this restart. Node.js differentiates between Resident Set Size (RSS), which represents the total memory allocated for the process, and the V8 Heap usage, which tracks the memory used by the application's objects.

If the threshold is based on RSS, the process may restart due to external buffer allocations or native modules, even if the V8 heap remains stable. Conversely, if it monitors the heap, it might ignore growth in the resident set.

Which specific memory metric does PM2 track to evaluate the max_memory_restart limit?
  Does this behavior change when running in cluster mode versus fork mode?

Tasadduq Burney · Answer

The Trigger Metric
PM2's max_memory_restart triggers based on the Resident Set Size (RSS), not the V8 heap usage. This means PM2 monitors the total physical memory allocated to the process by the operating system, including the heap, code segment, stack, and any memory used by native C++ modules.

RSS vs. Heap: Why it Matters
Because PM2 tracks RSS, a process may be restarted even if the Node.js heap remains well below its limit. This typically happens in the following scenarios:

Native Modules: Memory allocated by native addons (e.g., sharp, bcrypt, or canvas) exists outside the V8 heap but contributes to RSS.
  Buffers: Large Buffer allocations in newer Node.js versions are allocated outside the V8 heap (using ArrayBuffer), increasing RSS without affecting heap metrics.
  Memory Fragmentation: The OS may not immediately reclaim memory from the process, leading to a higher RSS than what the application is actively using.

Cluster vs. Fork Mode
The behavior remains consistent across both cluster and fork modes. In both instances, the PM2 daemon monitors the system-level memory usage of the individual child process. In cluster mode, each worker process is monitored independently against the max_memory_restart threshold.

Verification Steps
To verify which metric is causing your restarts, you can compare the internal Node.js heap usage against the system RSS using the following method:

Run pm2 monit to see the real-time memory usage reported by PM2 (this is the RSS).
  Inside your application, log the heap usage periodically:

console.log("Heap Used:", process.memoryUsage().heapUsed / 1024 / 1024, "MB");
console.log("RSS:", process.memoryUsage().rss / 1024 / 1024, "MB");
If the rss value in process.memoryUsage() closely matches the value in pm2 monit while heapUsed is significantly lower, the restart is being triggered by non-heap memory growth.

Diagnostic Note: Are you using any native C++ addons or processing large binary files via Buffers? If so, the RSS trigger is likely reacting to those specific allocations.

Does max_memory_restart trigger based on RSS or Heap usage?

1 answer

1 question comment

The Trigger Metric

RSS vs. Heap: Why it Matters

Cluster vs. Fork Mode

Verification Steps

Your perspective belongs here.