DOCSEARCHbyAlgolia
Submit Docs

node-heapdump

repository·master·Indexed 25 days ago

https://github.com/bnoordhuis/node-heapdump

A native Node.js addon used to create V8 heap snapshots for memory profiling and debugging. It provides the writeSnapshot() function to save the current state of the heap to a file and supports triggering snapshots via the SIGUSR2 signal on UNIX platforms.

Tokens
967
Snippets
3
Records
9
Agent score
82%

What's inside node-heapdump

  3. Inspect a heap snapshot in Google Chrome

    master

    To view the contents of a .heapsnapshot file:

    1. Open Google Chrome and press F12 to open Developer Tools.
    2. Navigate to the Memory tab.
    3. Right-click in the tab pane and select Load profile....
    4. Select your dump file and click Open.

    Important: Chrome will only load files that have the .heapsnapshot extension. Large snapshots may take minutes or even hours to load.

  4. Trigger a heap dump using SIGUSR2

    master

    On UNIX platforms, you can force a snapshot by sending the SIGUSR2 signal to the Node.js process using the kill command.

    To disable the default SIGUSR2 signal handler, set the NODE_HEAPDUMP_OPTIONS environment variable to nosignal.

  5. Troubleshoot empty or truncated heap snapshots

    master

    If your snapshot files are empty or truncated, it is likely due to resource exhaustion.

    Key Considerations:

    • Memory Requirement: On UNIX systems, creating a heap snapshot typically requires memory twice the size of the heap at the time of the snapshot.
    • OOM Killer: Check dmesg to see if the system's Out-Of-Memory (OOM) killer terminated the process.
    • Resource Limits: Check system limits like ulimit -u (max user processes) or ulimit -v (max virtual memory size).

  6. Handle SIGUSR2 to write snapshots to custom locations

    master

    You can intercept the SIGUSR2 signal in your application code to control where the snapshot is saved. It is recommended to check process.env.NODE_HEAPDUMP_OPTIONS to ensure you don't conflict with the nosignal setting.

    if (!/nosignal/.test(process.env.NODE_HEAPDUMP_OPTIONS)) {
  process.on("SIGUSR2", function() {
    heapdump.writeSnapshot('/var/local/' + Date.now() + '.heapsnapshot');
  });
}

  7. Configure heapdump via NODE_HEAPDUMP_OPTIONS

    master

    You can configure the behavior of node-heapdump using the NODE_HEAPDUMP_OPTIONS environment variable. This is processed during the initial module load.

    Supported options (comma-separated):

    • signal: Enables the use of signals to trigger heap dumps.
    • nosignal: Disables the use of signals to trigger heap dumps.

    Example: NODE_HEAPDUMP_OPTIONS="signal" node my-app.js

  8. Use writeSnapshot() to create a heap dump

    master

    The heapdump module exports a writeSnapshot([filename], [callback]) function.

    • filename: (Optional) The path where the snapshot will be saved. If omitted, the filename defaults to heapdump-<sec>.<usec>.heapsnapshot.
    • callback: (Optional) A function called upon completion. The callback receives (err, filename).

    Note: The snapshot is written synchronously to disk. For large JS heaps, this may cause a noticeable performance

  9. Create a V8 heap snapshot with writeSnapshot()

    master

    The writeSnapshot function allows you to trigger a V8 heap snapshot. It can be used to save the current state of the heap to a file for later inspection.

    Behavior:

    • If a filename is provided, the snapshot is written to that path.
    • If filename is omitted, the library uses a default filename.
    • The function is synchronous. While it accepts a callback, the underlying operation completes before the callback is invoked.
    • The function returns true if the snapshot was successful, and false if it failed.

    Arguments:

    • filename (string|function): The path where the snapshot should be saved. If you pass a function as the first argument, it is treated as the callback, and the filename will be undefined (using the default).
    • cb (function): A callback function that is called with (err, filename). On success, err is null and filename is the path to the snapshot. On failure, err is an Error object containing the error code or message.