profile-inspect 0.1.3

Analyze V8 CPU and heap profiles from Node.js/Chrome DevTools
Documentation

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:

Option Description
-f, --format <FORMAT> Output format: text, markdown, json, speedscope, collapsed (can specify multiple)
-o, --output <DIR> Output directory for generated files
--filter <CATEGORY> Filter by category: app, deps, node, v8, native
--focus <PATTERN> Focus on functions matching regex pattern
--exclude <PATTERN> Exclude functions matching regex pattern
--package <NAME> Focus analysis on a specific npm package
--sourcemap-dir <DIR> Directory containing source maps for bundled code
--include-internals Include Node.js and V8 internal functions
--min-percent <N> Only show functions with at least N% of total time
--top <N> Show only top N functions

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:

Option Description
-f, --format <FORMAT> Output format (can specify multiple)
-o, --output <DIR> Output directory
--include-internals Include Node.js and V8 internals
--min-percent <N> Minimum percentage to show
--top <N> Maximum number of functions to show

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:

Option Description
--min-delta <N> Only show functions with at least N% change

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:

Option Description
--function <NAME> Function name to explain (required)

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:

Option Description
--cpu Enable CPU profiling
--heap Enable heap profiling
-f, --format <FORMAT> Output format (can specify multiple)
-o, --output <DIR> Output directory
--filter <CATEGORY> Filter by category
--package <NAME> Focus on a specific npm package
--sourcemap-dir <DIR> Directory containing source maps
--profile-dir <DIR> Save profile files to this directory (preserves them)
--include-internals Include Node.js and V8 internals
--min-percent <N> Minimum percentage to show
--top <N> Maximum number of functions to show

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

Format Flag Description
Text -f text Human-readable terminal output (default)
Markdown -f markdown Markdown tables for documentation
JSON -f json Machine-readable JSON
Speedscope -f speedscope Import into speedscope.app
Collapsed -f collapsed Collapsed stack format for flame graphs

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:

Category Flag Description
App --filter app Your application code
Deps --filter deps Code from node_modules
Node --filter node Node.js built-in modules
V8 --filter v8 V8 JavaScript engine internals
Native --filter native Native C++ addons

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