### Install node-heapdump

Source: https://github.com/bnoordhuis/node-heapdump/blob/master/README.md

Install the heapdump module using npm.

```bash
npm install heapdump
```

--------------------------------

### Manually Install Custom SIGUSR2 Handler

Source: https://context7.com/bnoordhuis/node-heapdump/llms.txt

Installs a custom SIGUSR2 handler to write heap snapshots to a controlled location when the `nosignal` option is set via the environment variable.

```javascript
// When nosignal is set, install a custom SIGUSR2 handler manually
// to write snapshots to a controlled location
var heapdump = require('heapdump');

if (!/nosignal/.test(process.env.NODE_HEAPDUMP_OPTIONS)) {
  // Override the default signal handler with a custom path
  process.on('SIGUSR2', function() {
    var filename = '/var/diagnostics/myapp-' + Date.now() + '.heapsnapshot';
    heapdump.writeSnapshot(filename, function(err, file) {
      if (err) console.error('Snapshot error:', err.message);
      else console.log('Signal-triggered snapshot at:', file);
    });
  });
}
```

--------------------------------

### Capture Periodic Heap Snapshots

Source: https://context7.com/bnoordhuis/node-heapdump/llms.txt

Capture a baseline snapshot on startup and a comparison snapshot after a delay. Ensure the snapshot directory exists and is writable. Large snapshots may take time to generate.

```javascript
var heapdump = require('heapdump');
var path = require('path');
var snapshotDir = '/var/diagnostics';

// Capture baseline snapshot on startup
heapdump.writeSnapshot(path.join(snapshotDir, 'baseline.heapsnapshot'), function(err, file) {
  if (err) return console.error('Baseline snapshot failed:', err.message);
  console.log('Baseline snapshot captured:', file);
});

// Capture a comparison snapshot after 5 minutes
setTimeout(function() {
  heapdump.writeSnapshot(path.join(snapshotDir, 'after-5min.heapsnapshot'), function(err, file) {
    if (err) return console.error('Comparison snapshot failed:', err.message);
    console.log('Comparison snapshot captured:', file);
    // Load both files in Chrome DevTools > Memory > Load profile...
    // Switch to "Comparison" view to see objects allocated between the two snapshots
  });
}, 5 * 60 * 1000);
```

--------------------------------

### Build node-heapdump

Source: https://github.com/bnoordhuis/node-heapdump/blob/master/README.md

Build the native addon for node-heapdump.

```bash
node-gyp configure build
```

--------------------------------

### NODE_HEAPDUMP_OPTIONS environment variable

Source: https://context7.com/bnoordhuis/node-heapdump/llms.txt

Configures module-level behavior at startup via a comma-separated list of option tokens, primarily for controlling the SIGUSR2 signal handler.

```APIDOC
## `NODE_HEAPDUMP_OPTIONS` environment variable — Configure signal handler

### Description
Controls module-level behavior at startup via a comma-separated list of option tokens. The only supported tokens are `signal` (enable SIGUSR2 handler, default on UNIX) and `nosignal` (disable SIGUSR2 handler). This is read once when the module is first `require`'d.

### Usage
Set the environment variable before starting the Node.js process.

### Options
- **signal**: Enable the `SIGUSR2` signal handler (default on UNIX systems).
- **nosignal**: Disable the `SIGUSR2` signal handler.

### Request Example
```bash
# Default behavior: SIGUSR2 handler is enabled on UNIX
node server.js

# Disable the automatic SIGUSR2 handler
NODE_HEAPDUMP_OPTIONS=nosignal node server.js

# Explicitly enable the signal handler (redundant but valid)
NODE_HEAPDUMP_OPTIONS=signal node server.js
```

### Code Example
```js
// When nosignal is set, install a custom SIGUSR2 handler manually
// to write snapshots to a controlled location
var heapdump = require('heapdump');

if (!/nosignal/.test(process.env.NODE_HEAPDUMP_OPTIONS)) {
  // Override the default signal handler with a custom path
  process.on('SIGUSR2', function() {
    var filename = '/var/diagnostics/myapp-' + Date.now() + '.heapsnapshot';
    heapdump.writeSnapshot(filename, function(err, file) {
      if (err) console.error('Snapshot error:', err.message);
      else console.log('Signal-triggered snapshot at:', file);
    });
  });
}
```
```

--------------------------------

### Write heap snapshot with callback

Source: https://github.com/bnoordhuis/node-heapdump/blob/master/README.md

Write a heap snapshot and execute a callback function upon completion. The callback receives an error object and the filename of the snapshot.

```javascript
heapdump.writeSnapshot(function(err, filename) {
  console.log('dump written to', filename);
});
```

--------------------------------

### heapdump.writeSnapshot([filename], [callback])

Source: https://context7.com/bnoordhuis/node-heapdump/llms.txt

Captures the current V8 heap and writes it as a JSON-serialized `.heapsnapshot` file. The filename is optional, and a callback can be provided for asynchronous handling.

```APIDOC
## `heapdump.writeSnapshot([filename], [callback])` — Write a heap snapshot to disk

### Description
Captures the current V8 heap and writes it as a JSON-serialized `.heapsnapshot` file. The `filename` argument is optional; when omitted, a timestamped filename of the form `heapdump-<sec>.<usec>.heapsnapshot` is generated automatically in the current working directory. The optional `callback(err, filename)` follows the Node.js error-first convention and is invoked synchronously after the write completes. The function returns `true` on success and `false` on failure.

### Parameters
#### Path Parameters
- **filename** (string) - Optional - The path to save the heap snapshot file. If omitted, a timestamped filename is generated in the current working directory.

#### Callback Function
- **callback** (function) - Optional - A Node.js-style callback function `(err, filename)` that is invoked after the snapshot is written.
  - **err** (Error) - An error object if the write operation failed.
  - **filename** (string) - The name of the file that was written.

### Return Value
- **boolean** - `true` if the snapshot was written successfully, `false` otherwise.

### Request Example
```js
var heapdump = require('heapdump');

// 1. Auto-generated filename, no callback
var ok = heapdump.writeSnapshot();
// Writes e.g. "heapdump-1718000000.123456.heapsnapshot" to cwd
console.log('Snapshot written:', ok); // true

// 2. Custom filename, no callback
heapdump.writeSnapshot('/var/diagnostics/' + Date.now() + '.heapsnapshot');

// 3. Auto-generated filename with callback
heapdump.writeSnapshot(function(err, filename) {
  if (err) {
    console.error('Heap dump failed:', err.message);
    // e.g. "heapdump write error ENOENT" if the directory doesn't exist
    return;
  }
  console.log('Heap dump saved to:', filename);
  // => "Heap dump saved to: heapdump-1718000000.654321.heapsnapshot"
});

// 4. Custom filename with callback and error handling
heapdump.writeSnapshot('/var/diagnostics/myapp-' + Date.now() + '.heapsnapshot', function(err, filename) {
  if (err) {
    console.error('Failed to write heap dump:', err.message);
    return;
  }
  console.log('Heap dump written to:', filename);
  // => "Heap dump written to: /var/diagnostics/myapp-1718000000000.heapsnapshot"
});
```
```

--------------------------------

### Write Heap Snapshot with Callback (Custom Filename)

Source: https://context7.com/bnoordhuis/node-heapdump/llms.txt

Captures the V8 heap, writes it to a custom file path, and invokes a callback upon completion. Includes error handling for the write operation.

```javascript
// 4. Custom filename with callback and error handling
heapdump.writeSnapshot('/var/diagnostics/myapp-' + Date.now() + '.heapsnapshot', function(err, filename) {
  if (err) {
    console.error('Failed to write heap dump:', err.message);
    return;
  }
  console.log('Heap dump written to:', filename);
  // => "Heap dump written to: /var/diagnostics/myapp-1718000000000.heapsnapshot"
});
```

--------------------------------

### Signal Handling (SIGUSR2)

Source: https://github.com/bnoordhuis/node-heapdump/blob/master/README.md

On UNIX systems, the `heapdump` module can be configured to generate a heap snapshot when the process receives a SIGUSR2 signal.

```APIDOC
## Signal Handling (SIGUSR2)

### Description
Allows triggering a heap snapshot by sending a SIGUSR2 signal to the Node.js process. This feature is enabled by default but can be disabled via an environment variable.

### Method
Send `SIGUSR2` signal to the Node.js process.

### Usage
```bash
$ kill -USR2 <pid>
```

### Configuration
To disable signal handling, set the `NODE_HEAPDUMP_OPTIONS` environment variable to `nosignal`:

```bash
$ env NODE_HEAPDUMP_OPTIONS=nosignal node script.js
```

### Customizing Snapshot Location
You can catch the `SIGUSR2` signal to write the snapshot to a custom location:

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

--------------------------------

### Write Heap Snapshot with Custom Filename

Source: https://context7.com/bnoordhuis/node-heapdump/llms.txt

Captures the current V8 heap and writes it to a specified file path. Ensure the directory exists for successful writes.

```javascript
// 2. Custom filename, no callback
heapdump.writeSnapshot('/var/diagnostics/' + Date.now() + '.heapsnapshot');
```

--------------------------------

### Write Heap Snapshot with Callback (Auto-Generated Filename)

Source: https://context7.com/bnoordhuis/node-heapdump/llms.txt

Captures the V8 heap, writes it to an auto-generated filename, and invokes a callback upon completion. Handles potential errors during the write process.

```javascript
// 3. Auto-generated filename with callback
heapdump.writeSnapshot(function(err, filename) {
  if (err) {
    console.error('Heap dump failed:', err.message);
    // e.g. "heapdump write error ENOENT" if the directory doesn't exist
    return;
  }
  console.log('Heap dump saved to:', filename);
  // => "Heap dump saved to: heapdump-1718000000.654321.heapsnapshot"
});
```

--------------------------------

### Write heap snapshot with filename

Source: https://github.com/bnoordhuis/node-heapdump/blob/master/README.md

Write a heap snapshot to a specified file. If the filename is omitted, a default name is generated.

```javascript
heapdump.writeSnapshot('/var/local/' + Date.now() + '.heapsnapshot');
```

--------------------------------

### Write Heap Snapshot with Auto-Generated Filename

Source: https://context7.com/bnoordhuis/node-heapdump/llms.txt

Captures the current V8 heap and writes it to a file with an automatically generated timestamped filename. Returns true on success, false on failure.

```javascript
var heapdump = require('heapdump');

// 1. Auto-generated filename, no callback
var ok = heapdump.writeSnapshot();
// Writes e.g. "heapdump-1718000000.123456.heapsnapshot" to cwd
console.log('Snapshot written:', ok); // true
```

--------------------------------

### Inspect Heap Snapshot in Chrome DevTools

Source: https://context7.com/bnoordhuis/node-heapdump/llms.txt

Instructions for loading and analyzing a .heapsnapshot file in Chrome DevTools. Ensure the file has the .heapsnapshot extension. Loading large files may take several minutes.

```text
1. Open Google Chrome and navigate to any page.
2. Press F12 (or Cmd+Opt+I on macOS) to open DevTools.
3. Click the "Memory" tab.
4. Right-click anywhere in the left panel and select "Load profile...".
5. Select the .heapsnapshot file from disk and click "Open".
6. Use the "Summary" view to browse objects by constructor name.
7. Use the "Comparison" view (when two snapshots are loaded) to find leaked objects.
8. Use the "Containment" view to inspect the full object graph.

NOTE: Chrome requires the file to have the exact .heapsnapshot extension.
      Large snapshots (hundreds of MB) may take several minutes to load.
```

--------------------------------

### Force snapshot with SIGUSR2

Source: https://github.com/bnoordhuis/node-heapdump/blob/master/README.md

On UNIX systems, you can force a heap snapshot by sending the Node.js process a SIGUSR2 signal.

```bash
$ kill -USR2 <pid>
```

--------------------------------

### Load heapdump module

Source: https://github.com/bnoordhuis/node-heapdump/blob/master/README.md

Load the heapdump add-on in your Node.js application.

```javascript
var heapdump = require('heapdump');
```

--------------------------------

### writeSnapshot Function

Source: https://github.com/bnoordhuis/node-heapdump/blob/master/README.md

The `writeSnapshot` function is the primary method for generating a heap dump. It can optionally take a filename and a callback function.

```APIDOC
## heapdump.writeSnapshot([filename], [callback])

### Description
Writes a snapshot of the V8 heap to a file. If `filename` is omitted, a default name is generated. The `callback` function is executed upon completion.

### Method
`heapdump.writeSnapshot(filename, callback)
heapdump.writeSnapshot(callback)
heapdump.writeSnapshot(filename)
heapdump.writeSnapshot()

### Parameters
#### Path Parameters
- **filename** (string) - Optional - The desired path and name for the snapshot file. Defaults to `heapdump-<sec>.<usec>.heapsnapshot`.

#### Callback Function
- **callback** (function) - Optional - A function to be called after the snapshot is written. It receives `err` and `filename` as arguments.

### Request Example
```javascript
// With filename and callback
heapdump.writeSnapshot('/var/local/my-heap-dump.heapsnapshot', function(err, filename) {
  if (err) {
    console.error('Error writing heap dump:', err);
  } else {
    console.log('Heap dump written to:', filename);
  }
});

// With only callback
heapdump.writeSnapshot(function(err, filename) {
  console.log('dump written to', filename);
});

// With only filename
heapdump.writeSnapshot('/tmp/snapshot.heapsnapshot');

// No arguments (uses default filename)
heapdump.writeSnapshot();
```

### Response
#### Success Response
The function writes the heap snapshot to disk synchronously. The callback, if provided, will be invoked with `err` (null on success) and the `filename` of the created snapshot.
```

--------------------------------

### Handle SIGUSR2 for custom snapshot location

Source: https://github.com/bnoordhuis/node-heapdump/blob/master/README.md

Catch the SIGUSR2 signal to write the heap snapshot to a custom location, respecting the NODE_HEAPDUMP_OPTIONS environment variable.

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

--------------------------------

### SIGUSR2 signal

Source: https://context7.com/bnoordhuis/node-heapdump/llms.txt

On UNIX platforms, sending SIGUSR2 to the Node.js process triggers an automatic heap snapshot. This is enabled by default unless NODE_HEAPDUMP_OPTIONS=nosignal is set.

```APIDOC
## SIGUSR2 signal — Trigger a heap dump from outside the process

### Description
On UNIX platforms, sending `SIGUSR2` to the Node.js process triggers an automatic heap snapshot written to the current working directory. This requires no code changes and works with any Node.js application that has loaded the `heapdump` module. The signal handler is active by default unless `NODE_HEAPDUMP_OPTIONS=nosignal` is set.

### Usage
1. Find the Process ID (PID) of your running Node.js application.
2. Send the `SIGUSR2` signal to that PID using the `kill` command.

### Request Example
```bash
# Find the PID of your running Node.js application
$ pgrep -f "node server.js"
12345

# Send SIGUSR2 to trigger a heap dump
$ kill -USR2 12345
# A file like "heapdump-1718000000.123456.heapsnapshot" appears in the app's cwd

# Alternatively, use the full signal name
$ kill -SIGUSR2 12345

# Verify the snapshot file was created
$ ls -lh heapdump-*.heapsnapshot
-rw-r--r-- 1 user group 48M Jun 10 12:34 heapdump-1718000000.123456.heapsnapshot
```
```

--------------------------------

### Trigger Heap Dump via SIGUSR2 Signal

Source: https://context7.com/bnoordhuis/node-heapdump/llms.txt

On UNIX platforms, sending SIGUSR2 to a Node.js process that has loaded the heapdump module triggers an automatic heap snapshot. This requires no code changes and the signal handler is active by default unless disabled.

```bash
# Find the PID of your running Node.js application
$ pgrep -f "node server.js"
12345

# Send SIGUSR2 to trigger a heap dump
$ kill -USR2 12345
# A file like "heapdump-1718000000.123456.heapsnapshot" appears in the app's cwd

# Alternatively, use the full signal name
$ kill -SIGUSR2 12345

# Verify the snapshot file was created
$ ls -lh heapdump-*.heapsnapshot
-rw-r--r-- 1 user group 48M Jun 10 12:34 heapdump-1718000000.123456.heapsnapshot
```

--------------------------------

### Disable SIGUSR2 signal handler

Source: https://github.com/bnoordhuis/node-heapdump/blob/master/README.md

Disable the SIGUSR2 signal handler by setting the NODE_HEAPDUMP_OPTIONS environment variable to 'nosignal'.

```bash
$ env NODE_HEAPDUMP_OPTIONS=nosignal node script.js
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.