Skip to content
Open
Show file tree
Hide file tree
Changes from 21 commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
497b8de
Bun.pprof.heap: sampling native heap profiles in pprof format
Jarred-Sumner Sep 13, 2026
059572e
[autofix.ci] apply automated fixes
autofix-ci[bot] Sep 13, 2026
0e14446
Bun.pprof.heap: only read JavaScript frames that are known to be comp…
Jarred-Sumner Sep 14, 2026
fd69966
test: pprof heap assertions that hold whichever allocation a sample l…
Jarred-Sumner Sep 14, 2026
b0994c2
test: no RSS bound for the pprof heap leak case under ASAN
Jarred-Sumner Sep 14, 2026
2393b45
--pprof-heap: the thread that ends the process writes the profile
Jarred-Sumner Sep 14, 2026
f518f30
pprof: read a build id only from a PT_NOTE inside a readable PT_LOAD
Jarred-Sumner Sep 14, 2026
20c07f0
test: pprof heap fixtures run from a temporary copy, decoder bounds
Jarred-Sumner Sep 14, 2026
71cacf2
test: run the prebuilt pprof, not `go tool pprof`
Jarred-Sumner Sep 14, 2026
21d5103
test: pprof decoder rejects varints over 64 bits; scripts import Worker
Jarred-Sumner Sep 14, 2026
d4d6b48
Merge remote-tracking branch 'origin/main' into claude/pprof-heap
Jarred-Sumner Sep 14, 2026
29b62f5
--pprof-heap: under --watch a Worker's SIGINT asks the listener count
Jarred-Sumner Sep 14, 2026
7fd1e46
Merge remote-tracking branch 'origin/main' into claude/pprof-heap
Jarred-Sumner Sep 15, 2026
25d8b3e
Bun.pprof.heap: drop the fallbacks for mimalloc without its profile f…
Jarred-Sumner Sep 14, 2026
f568b0d
test: a pprof heap profile that starts when a Worker has been allocating
Jarred-Sumner Sep 14, 2026
d643c88
Bun.pprof.heap: what the intervals being drawn changes
Jarred-Sumner Sep 15, 2026
53441d6
test: pprof heap fixtures fail when their Worker exits early
Jarred-Sumner Sep 15, 2026
4e48ec2
Bun.pprof.heap: buckets that say the same are one sample
Jarred-Sumner Sep 15, 2026
78a050e
Bun.pprof.heap: a test for buckets that fold into one sample
Jarred-Sumner Sep 15, 2026
573c598
deps: mimalloc to oven-sh/mimalloc#47: a thread starts over with each…
Jarred-Sumner Sep 15, 2026
69883f5
Merge remote-tracking branch 'origin/main' into claude/pprof-heap
Jarred-Sumner Sep 15, 2026
8f360ce
pprof: what a heap profile session keeps is bounded
Jarred-Sumner Sep 15, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ members = [
"src/js_parser_jsc",
"src/js_printer",
"src/libdeflate_sys",
"src/pprof",
"src/libuv_sys",
"src/ast",
"src/ast_jsc",
Expand Down Expand Up @@ -411,6 +412,7 @@ bun_js_parser = { path = "src/js_parser" }
bun_js_parser_jsc = { path = "src/js_parser_jsc" }
bun_js_printer = { path = "src/js_printer" }
bun_libdeflate_sys = { path = "src/libdeflate_sys" }
bun_pprof = { path = "src/pprof" }
bun_libuv_sys = { path = "src/libuv_sys" }
bun_ast = { path = "src/ast" }
bun_ast_jsc = { path = "src/ast_jsc" }
Expand Down
58 changes: 58 additions & 0 deletions docs/project/benchmarking.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -299,3 +299,61 @@ bun --heap-prof --heap-prof-dir ./profiles script.js
| `--heap-prof-name <filename>` | Set output filename |
| `--heap-prof-dir <dir>` | Set output directory |
| `--heap-prof-interval <bytes>` | Accepted for Node.js compatibility (the snapshot is taken once at exit; JavaScriptCore has no allocation sampling to apply an interval to) |

## Native heap profiling (pprof)

`Bun.pprof.heap` samples the allocations of Bun's native allocator and writes a [pprof](https://github.com/google/pprof) heap profile. Each sample has the JavaScript and native frames that allocated. Use it to find what holds native memory: `ArrayBuffer` contents, strings, buffers inside Bun's APIs.

```ts
Bun.pprof.heap.start();
await work();
await Bun.write("heap.pb.gz", Bun.pprof.heap.stop());
```

To profile a whole run without changing the code:

```sh terminal icon="terminal"
bun --pprof-heap=heap.pb.gz script.js
```

Open the profile with any pprof viewer:

```sh terminal icon="terminal"
go tool pprof -http=: heap.pb.gz
go tool pprof -top -sample_index=alloc_space heap.pb.gz
```

[speedscope](https://www.speedscope.app) opens the same file. For continuous profiling, serve `Bun.pprof.heap.profile()` from an endpoint and point a profiler that scrapes pprof endpoints, such as Pyroscope or Parca, at it:

```ts
Bun.pprof.heap.start();

Bun.serve({
Comment thread
Jarred-Sumner marked this conversation as resolved.
Resolved
hostname: "127.0.0.1",
routes: {
"/debug/pprof/heap": () => new Response(Bun.pprof.heap.profile()),
},
fetch: () => new Response("hello"),
});
```

A profile names the functions and files of the program, so keep the endpoint off public interfaces: bind it to `127.0.0.1` as above, or put it behind the authentication the scraper uses.

| API / flag | Description |
| ------------------------------------------- | ----------------------------------------------------------------- |
| `Bun.pprof.heap.start({ sampleInterval? })` | Start profiling. `sampleInterval` is in bytes (default `524288`) |
| `Bun.pprof.heap.profile()` | The profile so far as a gzipped `Uint8Array`. Profiling continues |
| `Bun.pprof.heap.stop()` | Stop and return the profile |
| `Bun.pprof.heap.isRunning` | Whether a profile is running |
| `--pprof-heap[=<path>]` | Profile the whole run and write the profile on exit |
| `--pprof-heap-interval=<bytes>` | The sample interval for `--pprof-heap` |

Notes:

- The profile has four sample types: `alloc_objects`, `alloc_space`, `inuse_objects`, `inuse_space`. `inuse_*` is what was allocated since `start()` and not freed.
- There is one profile per process. It includes Workers and Bun's own threads. Samples have a `thread` label, and a `worker` label on a Worker's JavaScript thread. Filter with `-tagfocus=thread=...`.
- JavaScript objects are not sampled one by one. The garbage-collected heap shows up as the blocks it takes from the allocator. Use `--heap-prof` or `Bun.generateHeapSnapshot()` for objects.
- Native frames are addresses in a release build of Bun. To see function names, download the `bun-profile` build of the same version and pass it first: `go tool pprof -http=: ./bun-profile heap.pb.gz`.
- In an executable built with `bun build --compile`, and in code loaded from `--bytecode` output, a JavaScript frame has the line where its function starts, and a function that has not been named yet is `(anonymous)`.
- On macOS, memory that system frameworks allocate is not part of the profile.
- On Windows x64, samples have native frames only.
83 changes: 83 additions & 0 deletions packages/bun-types/bun.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5402,6 +5402,89 @@ declare module "bun" {
function order(v1: StringLike, v2: StringLike): -1 | 0 | 1;
}

/**
* Profiles in the [pprof](https://github.com/google/pprof) format (`profile.proto`), the format of
* `go tool pprof`, speedscope, Pyroscope and Parca.
*/
namespace pprof {
/**
* A sampling profile of the process's native heap.
*
* Bun's allocator takes a sample about once per `sampleInterval` allocated bytes and remembers
* the stack that allocated, JavaScript and native frames together, until the memory is
* freed. The profile has the four sample types of a Go heap profile: `alloc_objects`,
* `alloc_space`, `inuse_objects` and `inuse_space`.
*
* There is one heap profile per process. It covers every thread: Workers, the HTTP client
* and the thread pool. Samples carry a `thread` label with the name of the thread, and those
* taken on a Worker's JavaScript thread a `worker` label with its `threadId`.
*
* What it sees is memory from Bun's allocator: `ArrayBuffer` contents, strings, native
* objects, the buffers of Bun's APIs. The JavaScript heap shows up as the blocks the garbage
* collector takes from the allocator, attributed to the allocation that made it need
* another block, not as individual objects; for those, use {@link generateHeapSnapshot}.
* On macOS, memory that system frameworks allocate is not included. On Windows x64, samples
* have native frames only.
*
* The same profile can be written when the process exits, without a change to the code:
* `bun --pprof-heap[=<path>] [--pprof-heap-interval=<bytes>]`.
*
* @example
* ```ts
* Bun.pprof.heap.start();
* await work();
* await Bun.write("heap.pb.gz", Bun.pprof.heap.stop());
* // go tool pprof -http=: heap.pb.gz
* ```
*/
namespace heap {
interface StartOptions {
/**
* Average number of bytes allocated between two samples. A smaller interval gives a more
* detailed profile and costs more time.
*
* At least 65536 (64 KiB).
*
* @default 524288 (512 KiB)
*/
sampleInterval?: number | undefined;
}

/**
* Start the heap profile of this process.
*
* @throws if a heap profile is already running, in this thread or another
*/
function start(options?: StartOptions): void;

/**
* The profile so far, gzipped, as `go tool pprof` and the others read it. The profile keeps
* running: `alloc_*` count from {@link start}, `inuse_*` is what is live now. Serve it
* from an endpoint such as `/debug/pprof/heap` for a continuous profiler to scrape.
*
* Positions in code that a bundler or Bun's transpiler changed are mapped back through
* sourcemaps for frames of the calling thread and of Workers that have exited. Samples
* with a frame of another Worker that is still running have the positions of the code as
* it runs, and the label `generated=true`.
*
* @throws if no heap profile is running
*/
function profile(): Uint8Array<ArrayBuffer>;

/**
* Stop the heap profile and return it, like {@link profile}.
*
* @throws if no heap profile is running
*/
function stop(): Uint8Array<ArrayBuffer>;

/**
* Whether a heap profile is running in this process.
*/
const isRunning: boolean;
}
}

namespace unsafe {
/**
* Cast bytes to a `String` without copying. This is the fastest way to get a `String` from a `Uint8Array` or `ArrayBuffer`.
Expand Down
185 changes: 185 additions & 0 deletions src/bun_core/debug.rs
Original file line number Diff line number Diff line change
Expand Up @@ -280,6 +280,191 @@ impl StackIterator {

pub(crate) const PC_OFFSET: usize = StackIterator::PC_OFFSET;

/// [`StackIterator`] for a sampling profiler: `fps[i]` and the return address saved in it,
/// `pcs[i]`, for each frame from `fp` up, with one syscall per window of stack (Linux), bounded
/// by the thread's stack (Apple) or from `RtlCaptureStackBackTrace` (Windows, `fps` zeroed;
/// [`capture_frame_chain_bounded`] has the frame pointers there).
#[inline(never)]
pub fn capture_frame_chain(fp: usize, fps: &mut [usize], pcs: &mut [usize]) -> usize {
let cap = fps.len().min(pcs.len());
let (fps, pcs) = (&mut fps[..cap], &mut pcs[..cap]);
if cfg!(miri) || cap == 0 {
return 0;
}
#[cfg(windows)]
{
let _ = fp;
fps.fill(0);
// SAFETY: `pcs` is valid for `cap` writes; the hash out-param may be null.
return unsafe {
bun_windows_sys::ntdll::RtlCaptureStackBackTrace(
// This function and its caller.
2,
cap.min(u16::MAX as usize) as u32,
pcs.as_mut_ptr().cast::<*mut core::ffi::c_void>(),
core::ptr::null_mut(),
)
} as usize;
}
#[cfg(any(target_os = "linux", target_os = "android"))]
{
static WINDOW_READS_REFUSED: core::sync::atomic::AtomicBool =
core::sync::atomic::AtomicBool::new(false);
if !WINDOW_READS_REFUSED.load(core::sync::atomic::Ordering::Relaxed) {
if let Some(n) = capture_frame_chain_windowed(fp, fps, pcs) {
return n;
}
WINDOW_READS_REFUSED.store(true, core::sync::atomic::Ordering::Relaxed);
}
}
#[cfg(target_vendor = "apple")]
{
return capture_frame_chain_bounded(fp, fps, pcs);
}
#[cfg(not(any(windows, target_vendor = "apple")))]
{
let mut it = StackIterator::init(fp);
let mut n = 0usize;
while n < cap {
let frame = it.fp;
match it.next() {
Some(pc) => {
fps[n] = frame;
pcs[n] = pc;
n += 1;
}
None => break,
}
}
n
}
}

/// `None`: the kernel refused `process_vm_readv` on our own pid (seccomp, qemu-user).
#[cfg(any(target_os = "linux", target_os = "android"))]
fn capture_frame_chain_windowed(
mut fp: usize,
fps: &mut [usize],
pcs: &mut [usize],
) -> Option<usize> {
const WORD: usize = core::mem::size_of::<usize>();
const WINDOW_WORDS: usize = 1024;
let mut window = [0usize; WINDOW_WORDS];
// The words of `window` that hold the stack at `[base, base + have)`.
let (mut base, mut have) = (0usize, 0usize);
let mut n = 0usize;
// SAFETY: no preconditions. Not cached: after fork() the pid is another one.
let pid = unsafe { libc::getpid() };
while n < fps.len() {
let Some(frame) = fp.checked_sub(StackIterator::FP_OFFSET) else {
break;
};
if frame == 0 || frame % core::mem::align_of::<usize>() != 0 {
break;
}
let Some(last_word) = frame.checked_add(StackIterator::PC_OFFSET) else {
break;
};
if frame < base || last_word.saturating_add(WORD) > base + have {
let local = libc::iovec {
iov_base: window.as_mut_ptr().cast(),
iov_len: core::mem::size_of_val(&window),
};
let remote = libc::iovec {
iov_base: frame as *mut core::ffi::c_void,
iov_len: core::mem::size_of_val(&window),
};
// SAFETY: `local` is a writable buffer of the stated size. A `remote` range that is
// not mapped gives a short count or EFAULT.
let got = unsafe {
libc::process_vm_readv(pid, &raw const local, 1, &raw const remote, 1, 0)
};
if got < 0 {
if crate::ffi::errno() == libc::EFAULT {
break;
}
return if n == 0 { None } else { Some(n) };
}
base = frame;
have = got as usize;
if last_word + WORD > base + have {
break;
}
}
let next_fp = window[(frame - base) / WORD];
let pc = window[(last_word - base) / WORD];
if pc == 0 {
break;
}
fps[n] = fp;
pcs[n] = pc;
n += 1;
// The stack grows down: a caller's frame is above its callee's.
if next_fp <= fp {
break;
}
fp = next_fp;
}
Some(n)
}

/// The frame-pointer chain from `fp` as far as it stays inside the calling thread's stack:
/// every hop is checked against the stack's bounds before it is read. Not for x64 Windows,
/// where rbp points into the frame and not at a saved rbp.
#[cfg(any(target_vendor = "apple", all(windows, target_arch = "aarch64")))]
pub fn capture_frame_chain_bounded(mut fp: usize, fps: &mut [usize], pcs: &mut [usize]) -> usize {
const WORD: usize = core::mem::size_of::<usize>();
let cap = fps.len().min(pcs.len());
let (fps, pcs) = (&mut fps[..cap], &mut pcs[..cap]);
#[cfg(target_vendor = "apple")]
let (bottom, top) = {
// SAFETY: no preconditions; `pthread_self()` is the calling thread.
let (top, size) = unsafe {
let this = libc::pthread_self();
(
libc::pthread_get_stackaddr_np(this) as usize,
libc::pthread_get_stacksize_np(this),
)
};
(top.saturating_sub(size), top)
};
#[cfg(windows)]
let (bottom, top) = bun_windows_sys::current_thread_stack_bounds();
let mut n = 0usize;
while n < fps.len() {
let Some(frame) = fp.checked_sub(StackIterator::FP_OFFSET) else {
break;
};
let Some(last_word) = frame.checked_add(StackIterator::PC_OFFSET) else {
break;
};
if frame % core::mem::align_of::<usize>() != 0
|| frame < bottom
|| last_word.saturating_add(WORD) > top
{
break;
}
// SAFETY: `[frame, last_word + WORD)` lies inside this thread's stack.
let (next_fp, pc) = unsafe {
(
core::ptr::read(frame as *const usize),
core::ptr::read(last_word as *const usize),
)
};
if pc == 0 {
break;
}
fps[n] = fp;
pcs[n] = pc;
n += 1;
if next_fp <= fp {
break;
}
fp = next_fp;
}
n
}

/// Capture the current thread's call stack.
///
/// POSIX: walk frame pointers. Windows: `RtlCaptureStackBackTrace` via
Expand Down
Loading
Loading