mirror of
https://github.com/oven-sh/bun
synced 2026-02-02 15:08:46 +00:00
3b1c3bfe97
## Summary
- Add `--heap-prof` CLI flag for generating V8-compatible heap snapshots
(`.heapsnapshot`)
- Add `--heap-prof-md` CLI flag for generating markdown heap profiles
(`.md`) designed for CLI analysis
- Add `--heap-prof-name` and `--heap-prof-dir` options for customizing
output location
## Usage
```bash
# Generate V8-compatible heap snapshot (opens in Chrome DevTools)
bun --heap-prof script.js
# Generate markdown heap profile (for CLI analysis with grep/sed/awk)
bun --heap-prof-md script.js
# Specify output location
bun --heap-prof --heap-prof-dir ./profiles --heap-prof-name my-snapshot.heapsnapshot script.js
```
## Example Output (`--heap-prof-md`)
<details>
<summary>Click to expand example markdown profile</summary>
```markdown
# Bun Heap Profile
Generated by `bun --heap-prof-md`. This profile contains complete heap data in markdown format.
**Quick Search Commands:**
```bash
grep 'type=Function' file.md # Find all Function objects
grep 'size=[0-9]\{5,\}' file.md # Find objects >= 10KB
grep 'EDGE.*to=12345' file.md # Find references to object #12345
grep 'gcroot=1' file.md # Find all GC roots
```
---
## Summary
| Metric | Value |
|--------|------:|
| Total Heap Size | 208.2 KB (213265 bytes) |
| Total Objects | 2651 |
| Total Edges | 7337 |
| Unique Types | 73 |
| GC Roots | 426 |
## Top 50 Types by Retained Size
| Rank | Type | Count | Self Size | Retained Size | Largest Instance |
|-----:|------|------:|----------:|--------------:|-----------------:|
| 1 | `Function` | 568 | 18.7 KB | 5.4 MB | 10.4 KB |
| 2 | `Structure` | 247 | 27.0 KB | 2.0 MB | 10.4 KB |
| 3 | `FunctionExecutable` | 306 | 38.2 KB | 375.5 KB | 13.0 KB |
| 4 | `FunctionCodeBlock` | 25 | 21.5 KB | 294.1 KB | 14.0 KB |
| 5 | `string` | 591 | 11.3 KB | 75.9 KB | 177 B |
...
## Top 50 Largest Objects
Objects that retain the most memory (potential memory leak sources):
| Rank | ID | Type | Self Size | Retained Size | Out-Edges | In-Edges |
|-----:|---:|------|----------:|--------------:|----------:|---------:|
| 1 | 0 | `<root>` | 0 B | 58.1 KB | 852 | 0 |
| 2 | 774 | `GlobalObject` | 10.0 KB | 41.9 KB | 717 | 807 |
| 3 | 600 | `ModuleProgramCodeBlock` | 1.2 KB | 23.9 KB | 30 | 1 |
...
## Retainer Chains
How the top 20 largest objects are kept alive (path from GC root to object):
### 1. Object #0 - `<root>` (58.1 KB retained)
```
(no path to GC root found)
```
### 2. Object #774 - `GlobalObject` (41.9 KB retained)
```
GlobalObject#774 [ROOT] (this object is a GC root)
```
...
## GC Roots
| ID | Type | Size | Retained | Label |
|---:|------|-----:|---------:|-------|
| 0 | `<root>` | 0 B | 58.1 KB | |
| 774 | `GlobalObject` | 10.0 KB | 41.9 KB | |
...
<details>
<summary>Click to expand 2651 objects (searchable with grep)</summary>
| ID | Type | Size | Retained | Flags | Label |
|---:|------|-----:|---------:|-------|-------|
| 0 | `<root>` | 0 | 59467 | gcroot=1 | |
| 1 | `Structure` | 112 | 10644 | | |
...
</details>
```
</details>
## Test plan
- [x] `bun bd test test/cli/heap-prof.test.ts` - All 7 tests pass
- [x] `USE_SYSTEM_BUN=1 bun test test/cli/heap-prof.test.ts` - Tests
fail (feature not in system bun)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>