# 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
```bash
cargo install profile-inspect
```
### From source
```bash
git clone https://github.com/Dunqing/profile-inspecting
cd profile-inspecting
cargo install --path .
```
### Pre-built binaries
Download from [GitHub Releases](https://github.com/Dunqing/profile-inspecting/releases).
## Quick Start
```bash
# 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:**
| `-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:**
```bash
# 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
# Exclude test files from analysis
# 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:**
| `-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:**
```bash
# 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:**
| `--min-delta <N>` | Only show functions with at least N% change |
**Examples:**
```bash
# 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:**
| `--function <NAME>` | Function name to explain (required) |
**Examples:**
```bash
# 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:**
| `--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:**
```bash
# 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
| 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](https://speedscope.app) |
| Collapsed | `-f collapsed` | Collapsed stack format for flame graphs |
You can specify multiple formats to generate all at once:
```bash
profile-inspect cpu app.cpuprofile -f json -f markdown -f collapsed -o ./reports
```
---
## Categories
Functions are automatically classified into categories:
| 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
```bash
node --cpu-prof --cpu-prof-name=profile.cpuprofile your-script.js
```
### Node.js Heap Profile
```bash
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
```bash
# 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