profile-inspect

A fast CLI tool for analyzing V8 CPU and heap profiles from Node.js and Chrome DevTools.

Features

• Analyze .cpuprofile and .heapprofile files
• Compare two profiles to find performance regressions
• Focus on specific functions with caller/callee analysis
• Run commands with profiling enabled and get instant analysis
• Filter by category: app code, dependencies, Node.js internals, V8 internals
• Source map support for bundled code
• Multiple output formats: text, markdown, JSON, speedscope, collapsed stacks

Installation

From crates.io

cargo install profile-inspect

From source

git clone https://github.com/Dunqing/profile-inspecting
cd profile-inspecting
cargo install --path .

Pre-built binaries

Download from GitHub Releases.

Quick Start

# Analyze a CPU profile
profile-inspect cpu profile.cpuprofile

# Run a command with profiling and instant analysis
profile-inspect run --cpu npm test

# Compare two profiles
profile-inspect diff before.cpuprofile after.cpuprofile

CLI Reference

profile-inspect cpu

Analyze a CPU profile file.

profile-inspect cpu [OPTIONS] <INPUT>

Arguments:

• <INPUT> - Path to .cpuprofile file

Options:

Examples:

# Basic analysis with default text output
profile-inspect cpu app.cpuprofile

# Show only your app code, exclude dependencies
profile-inspect cpu app.cpuprofile --filter app

# Focus on parsing-related functions
profile-inspect cpu app.cpuprofile --focus "parse|Parser"

# Exclude test files from analysis
profile-inspect cpu app.cpuprofile --exclude "\.test\.|__tests__"

# Analyze a specific package's performance
profile-inspect cpu app.cpuprofile --package lodash

# Output as JSON and Markdown to a directory
profile-inspect cpu app.cpuprofile -f json -f markdown -o ./reports

# With source maps for bundled code
profile-inspect cpu bundle.cpuprofile --sourcemap-dir ./dist

# Show functions taking at least 1% of time, top 50
profile-inspect cpu app.cpuprofile --min-percent 1 --top 50

# Include V8 and Node.js internals
profile-inspect cpu app.cpuprofile --include-internals

profile-inspect heap

Analyze a heap profile file.

profile-inspect heap [OPTIONS] <INPUT>

Arguments:

• <INPUT> - Path to .heapprofile file

Options:

Examples:

# Basic heap analysis
profile-inspect heap memory.heapprofile

# Show top 20 memory allocators
profile-inspect heap memory.heapprofile --top 20

# Output as JSON
profile-inspect heap memory.heapprofile -f json -o ./reports

profile-inspect diff

Compare two CPU profiles to find performance changes.

profile-inspect diff [OPTIONS] <BEFORE> <AFTER>

Arguments:

• <BEFORE> - Path to the "before" profile (baseline)
• <AFTER> - Path to the "after" profile (comparison)

Options:

Examples:

# Compare two profiles
profile-inspect diff baseline.cpuprofile optimized.cpuprofile

# Show only significant changes (>2%)
profile-inspect diff baseline.cpuprofile optimized.cpuprofile --min-delta 2

profile-inspect explain

Show callers and callees for a specific function.

profile-inspect explain --function <NAME> <INPUT>

Arguments:

• <INPUT> - Path to profile file

Options:

Examples:

# Explain who calls processRequest and what it calls
profile-inspect explain app.cpuprofile --function processRequest

# Works with partial matches
profile-inspect explain app.cpuprofile --function "JSON.parse"

profile-inspect run

Run a command with profiling enabled and analyze the results.

profile-inspect run [OPTIONS] [CMD]...

Arguments:

• [CMD]... - Command to run (specify after all flags)

Options:

Examples:

# Run tests with CPU profiling
profile-inspect run --cpu npm test

# Run with both CPU and heap profiling
profile-inspect run --cpu --heap node server.js

# Profile and focus on a specific package
profile-inspect run --cpu --package express node app.js

# Save profiles for later analysis
profile-inspect run --cpu --profile-dir ./profiles npm run build

# Run with source map support
profile-inspect run --cpu --sourcemap-dir ./dist node dist/index.js

# Profile a complex command
profile-inspect run --cpu -- node --max-old-space-size=4096 build.js

Output Formats

You can specify multiple formats to generate all at once:

profile-inspect cpu app.cpuprofile -f json -f markdown -f collapsed -o ./reports

Categories

Functions are automatically classified into categories:

Generating Profiles

Node.js CPU Profile

node --cpu-prof --cpu-prof-name=profile.cpuprofile your-script.js

Node.js Heap Profile

node --heap-prof --heap-prof-name=profile.heapprofile your-script.js

Chrome DevTools

1. Open DevTools (F12)
2. Go to Performance tab
3. Click Record, perform actions, stop recording
4. Right-click on the profile and "Save profile..."

Development

# Setup development tools
just setup

# Run checks
just check

# Run tests
just test

# Build release
just build

# Release a new version
just release patch  # or minor, major

License

MIT