Interactive debugging tells you what is wrong now; continuous profiling tells you what has been slow for the past hour. The pprof Node module captures sampled CPU and heap profiles in Google’s pprof format, dumps them to disk, and lets you view them in the pprof web UI or Google’s Cloud Profiler. This walks through wiring it into a service, the on-disk format, and the alternatives (0x, Clinic.js Flame, --prof) you reach for when pprof isn’t a good fit.
How to verify
Confirm a profiler is loaded and capture a one-shot profile to sanity-check the toolchain:
curl -s http://127.0.0.1:3000/_debug/pprof/profile?seconds=30 > /tmp/cpu.pb.gz
file /tmp/cpu.pb.gz
go tool pprof -http=:8080 /tmp/cpu.pb.gz # if Go is installed
pprof -http=:8080 /tmp/cpu.pb.gz # standalone pprof binary
ls -lh /var/log/myapp/profiles/ # rotated profile dumps
Open the URL the pprof server prints — you should see a flame graph with V8 frames at the bottom and your application JS on top. If you see only (unknown) symbols, the profile lost symbolization: re-capture without minification or with source maps enabled.
What’s happening
The pprof Node package wraps V8’s CpuProfiler (for CPU) and the heap-sampling profiler (for memory) and serializes the result to Google’s protobuf-based pprof format. V8’s sampling CPU profiler records the stack on a timer interrupt — about 1000 samples per second by default — which adds roughly 2-5% CPU overhead. The heap profiler samples allocations using V8’s HeapProfiler::StartSamplingHeapProfiler and reports allocations weighted by sample interval.
pprof is the de-facto profile format across Go, Node, Python, JVM. Storing profiles in pprof means a single viewer (the pprof CLI, Pyroscope, Grafana Cloud Profiler) can render flame graphs, top tables, and source listings without per-language tooling. The format is dense — a 30 s CPU profile is typically 50-200 KiB compressed.
The procedure
-
Install pprof and wire it into your service:
npm install pprofimport express from 'express'; import pprof from 'pprof'; const app = express(); pprof.heap.start(512 * 1024, 64); // sample every 512 KiB, 64-frame depth app.get('/_debug/pprof/profile', async (req, res) => { const seconds = Math.min(parseInt(req.query.seconds) || 30, 120); const profile = await pprof.time.profile({ durationMillis: seconds * 1000 }); const buf = await pprof.encode(profile); res.set('Content-Type', 'application/octet-stream').send(buf); }); app.get('/_debug/pprof/heap', async (req, res) => { const profile = pprof.heap.profile(); res.send(await pprof.encode(profile)); }); -
Bind the debug routes to localhost only, behind an SSH tunnel or an internal-only listener. Anyone who can hit
/_debug/pprofcan DoS the process by repeatedly asking for 120 s profiles:app.use('/_debug', (req, res, next) => req.ip === '127.0.0.1' ? next() : res.status(403).end() ); -
Add a scheduled dumper that writes a profile every five minutes to disk, with rotation:
import { writeFile } from 'node:fs/promises'; import { gzipSync } from 'node:zlib'; setInterval(async () => { const profile = await pprof.time.profile({ durationMillis: 30_000 }); const buf = gzipSync(await pprof.encode(profile)); const name = `/var/log/myapp/profiles/cpu-${Date.now()}.pb.gz`; await writeFile(name, buf); }, 5 * 60_000).unref(); -
Add log rotation so the disk doesn’t fill up. A logrotate fragment at
/etc/logrotate.d/myapp-profiles:/var/log/myapp/profiles/*.pb.gz { daily rotate 7 maxsize 500M missingok notifempty } -
To view a profile interactively, ship it to your laptop and open it:
scp deploy@app-01:/var/log/myapp/profiles/cpu-1717362000000.pb.gz . pprof -http=:8080 cpu-1717362000000.pb.gzIn the browser go to
/ui/flamegraphfor the flame graph or/ui/topfor the top hot functions.
Common pitfalls
- Source maps are not in the profile by default. If your service is bundled or transpiled, the stack frames will show generated names. Use
--enable-source-mapsat boot and the profile will use original symbols. - The heap profiler reports allocations, not residency. A function allocating a lot but releasing immediately looks heavy; that’s not a leak. Use heap snapshots from Chrome DevTools for residency.
- A 120 s profile blocks the process from being GC’d cleanly during capture — V8 holds the CPU sample buffer the entire time. On 1 GiB containers this can push RSS over the limit.
0xand Clinic.js Flame call into the same V8 profiler but emit HTML reports instead of pprof; they’re easier ad-hoc but harder to feed into a continuous profiler. Use them for one-off investigation, pprof for the always-on case.- For container deployments, mount the profile directory as a volume — otherwise profiles are lost on container restart.
For interactive flame-graph capture without writing files, see Chrome DevTools profiling. In the engagements Stack Harbor runs, continuous pprof is wired into every Node service as part of managed operations, with profiles rotated to S3 and a Pyroscope endpoint for the on-call team to query without SSH’ing into each box.