Node.js Allocation Profiler

A command line tool for profiling Node.js memory allocations using Chrome DevTools Protocol. This tool helps you understand memory allocation patterns in your Node.js applications by tracking heap allocations and providing detailed analysis.

Features

• Heap Allocation Tracking: Uses Chrome DevTools Protocol to track memory allocations
• Function-level Analysis: Analyze allocations by function name patterns
• Tree Structure Visualization: View detailed allocation trees with function information
• Flexible Output: Save heaptimeline files or just view summaries
• Pattern Matching: Use regex patterns to focus on specific functions

Installation

Global Installation (Recommended)

npm install -g node-allocation-profiler

Local Installation

npm install node-allocation-profiler

Then use with npx:

npx node-allocation-profiler <target.js>

Usage

Basic Usage

node-allocation-profiler <target.js>

This will profile the target script and show allocation summaries for functions matching the default pattern ^benchmark.

Command Line Options

• --save-heaptimeline[=filename] - Save heaptimeline file (generates filename if not specified)
• --function-pattern=pattern - Regex pattern to match function names (default: /^benchmark/)
• --print-tree - Print the full allocation tree structure
• --help, -h - Show help message
• --version, -v - Show version information

Examples

Profile a script with default settings

node-allocation-profiler my-script.js

Save heaptimeline file with auto-generated filename

node-allocation-profiler my-script.js --save-heaptimeline

Save heaptimeline file with custom filename

node-allocation-profiler my-script.js --save-heaptimeline=my-profile.heaptimeline

Profile functions matching a specific pattern

node-allocation-profiler my-script.js --function-pattern="^test"

Show full allocation tree for all functions

node-allocation-profiler my-script.js --function-pattern=".*" --print-tree

Profile benchmark functions with detailed tree view

node-allocation-profiler my-script.js --print-tree

How It Works

1. Process Launch: The tool launches your target script with Node.js inspector enabled
2. Allocation Tracking: Enables heap allocation tracking via Chrome DevTools Protocol
3. Execution: Resumes script execution and waits for completion
4. Snapshot: Takes a heap snapshot when the script finishes
5. Analysis: Parses the snapshot and analyzes allocation patterns
6. Output: Displays results based on your specified options

Target Script Requirements

Your target script should:

1. Signal Completion: Output __PROFILE_DONE__ to stderr when finished
2. Be Profilable: Work with Node.js inspector (most scripts do)

Example target script:

// Your profiling target
function benchmark() {
  // Your code here
}

benchmark();
console.error('__PROFILE_DONE__');

Output Format

The tool provides:

• Function Information: Name, script location, line/column numbers
• Allocation Metrics: Count and size of allocations
• Per-iteration Stats: Normalized metrics (assuming 10k iterations)
• Tree Structure: Hierarchical view of allocation calls (when --print-tree is used)

File Structure

node-allocation-profiler/
├── bin/
│   └── node-allocation-profiler.js    # Command line interface
├── lib/
│   ├── allocation-profile.js           # Profile parsing logic
│   ├── analyzer.js                     # Analysis and output formatting
│   ├── profiler.js                     # Chrome DevTools Protocol integration
│   ├── utils.js                        # Utility functions
│   └── index.js                        # Main exports
├── package.json
└── README.md

Dependencies

• chrome-remote-interface - Chrome DevTools Protocol client
• Node.js 16+ (for ES modules support)

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.