Node.js profiling: CPU profiles, flame graphs, and production sampling

Find Node.js CPU hotspots with --cpu-prof, Chrome DevTools, Inspector, and Linux perf. Learn how flame graphs differ from timelines and where continuous profiling fits.

Best practices
Node.js event loop and asynchronous task flow illustration

A Node.js process can use nearly all of a CPU while its slowest request is waiting on a database. Those are different questions. Start with node --cpu-prof app.js when you need to see where execution time goes, then load the resulting .cpuprofile in Chrome DevTools. Continuous profiling can add production context for intervals you have actually collected and retained.

Separate CPU work from I/O waits

High CPU may come from application code, garbage collection, native modules, or kernel work. Check user and system CPU alongside process load before choosing a tool. High system load is not synonymous with high CPU utilization: blocked I/O, exhausted connections, and slow dependencies can make requests slow without leaving an obvious JavaScript CPU hotspot.

A CPU profile describes sampled execution. Host metrics and distributed traces supply the other part of the investigation: how long the request waited and which dependency it waited for.

Capture a profile with the built-in profiler

node --cpu-prof app.js          # Sample from startup; write the profile on normal exit
# Alternatively, choose an output directory before starting the process
mkdir -p /tmp/profiles
node --cpu-prof --cpu-prof-dir=/tmp/profiles app.js

Choose one of the two node commands. Both begin sampling at startup. --cpu-prof-dir changes the destination; it does not attach a profiler on demand. The first command writes to the working directory by default, unless --diagnostic-dir changes it. The second needs write access to /tmp/profiles. These directory commands assume a Unix-like shell; use an appropriate path on other platforms.

Let the application exit normally, then look for the .cpuprofile file. A process killed with SIGKILL or forcibly terminated by its runtime may not finish writing it. For a long-running service that needs a bounded recording window, use Inspector recording instead.

Node's separate --prof option produces V8 log output for --prof-process. That output is not a .cpuprofile file. Keep the collection and analysis formats paired.

Read the result in Chrome DevTools

Load the .cpuprofile in the Performance panel. The old JS Profiler panel is deprecated; current instructions use Performance.

  • A flame chart places recorded execution on a timeline. It helps you see when a hotspot occurred. An aggregated flame graph, also written flamegraph, merges matching stacks instead: horizontal position is not chronological, and width represents sample weight or the corresponding share of time.
  • A wide frame includes work in its children. A broad exposed plateau can suggest expensive own work, but check Self Time against Total Time before blaming a wide parent function. Total includes child calls; self excludes them.
  • Bottom-Up aggregates activity over the selected recording interval. Sort by Self Time or Total Time, then follow the callers back to the code. File and line attribution depends on available source and source maps.

Use Inspector or Linux perf when you need a different view

Inspector lets you control the recording window interactively. In a controlled debugging environment, start node --inspect app.js, connect through chrome://inspect, and start and stop recording in Performance. The default listener is 127.0.0.1:9229. A connected debugger can control the application's execution environment, so keep the port off the public internet; use a controlled tunnel for remote access.

Linux perf can expose native-module, V8, and kernel execution that a JavaScript-focused view does not explain. For an existing target, perf record -F 99 -p <pid> -g requests sampling at 99 Hz with call chains. Stop perf when the recording is complete, then process it with tools such as perf script.

That command needs compatible Linux perf tooling, permission to sample the target, and usable stack unwinding. Readable JavaScript names may also require Node startup flags such as --perf-basic-prof-only-functions and --interpreted-frames-native-stack, with accessible JIT mappings and native symbols. Results depend on Node/V8, the kernel, and container permissions. Do not assume a complete JavaScript stack appears by default or loosen system-wide sampling permissions just to run the example.

Keep production profiles for the periods that matter

An incident in production may be difficult to reproduce after the fact. Continuous profiling keeps sampling during configured periods so you can compare collected profiles before and after a regression, within their retention window.

Profiles add another signal alongside metrics, logs, and traces. They cannot recover periods before collection was enabled or fill gaps in sampling, and they complement targeted manual recordings. Coverage and overhead depend on the profile type, frequency, and workload; there is no single fixed overhead to promise.

Compare a hotspot with request behavior

A hotspot from a local profile still needs production context. Guance's Node.js profiling integration documents a Pyroscope path: instrument the application with @pyroscope/nodejs, enable the separate Profile receiver in DataKit, and configure the service, environment, and version fields so profiles from a deployment can be filtered consistently.

The SDK's serverAddress must point to a DataKit Pyroscope receiver the application can reach. Check the deployed DataKit, SDK, and Node.js versions, operating system, and required profile types together. Current Pyroscope SDK documentation requires wall.collectCpuTime to be explicitly enabled for CPU collection; a default wall profile is not the same measurement as a CPU profile.

APM and profiling use different ingestion paths. Enabling APM alone does not collect function-level profiles, and matching service fields does not automatically establish per-span correlation. Measure sampling overhead in staging, then compare hotspots and request latency for the same version under similar load.

Setup: Node.js profiling, Node.js APM, and the Pyroscope Node.js SDK.

Frequently asked questions

How much overhead does profiling add?

It depends on the workload, sampling frequency, and analysis options. Compare throughput, latency, and memory in staging before choosing a production collection window. Continuous profiling also needs its own configuration and assessment.

How do I make sense of a flame graph?

Use Self Time to find expensive own work, distinguish JavaScript, native, and GC frames, and compare with a normal period. A large GC share means collection consumed substantial execution time. Allocation churn, object lifetimes, and heap settings may all contribute. It does not prove a memory leak or rule out allocation-heavy application algorithms.

How is asynchronous code represented?

Event-loop callbacks execute across separate ticks. A CPU profile records the execution stacks sampled during those callbacks; it does not charge the entire time spent awaiting a database to the function's own CPU time. Use tracing for end-to-end duration and dependency waits. Wall-time or off-CPU analysis needs a collector that supports that profile type; a CPU profile cannot supply it by inference.


References

This guide is based on public documentation. Validate examples against your project's dependency versions; documented performance characteristics are not measurements from this project.

Further reading

Get a tailored plan

Contact us

Join the community

Scan with WeChat
to join the community

Try Guance

Start online and pay only for what you use.

Get started

Choose a Guance plan

Code hosting