Week 23: Node.js Performance — Profiling, Worker Threads & the Event Loop

1. Profiling with the Inspector & clinic.js

"This endpoint feels slow" is a hypothesis, not a diagnosis. Node ships a built-in inspector (the same V8 profiler Chrome DevTools uses) that gives you an exact breakdown of where CPU time was actually spent:

node --prof dist/server.js
# ... generate load against the server, then stop it ...
node --prof-process isolate-0x*.log > profile.txt

clinic.js wraps the same underlying tooling into a friendlier workflow that produces an interactive flame graph directly:

npx clinic flame -- node dist/server.js
# generate load with autocannon or a load test in another terminal, then Ctrl+C
# opens an interactive flame graph in your browser

A flame graph makes the "which function actually dominates CPU time" question visual — wide bars are functions where a lot of sampled time landed. Running it against real traffic patterns, not a synthetic microbenchmark, is what makes the result trustworthy: a function that looks expensive in isolation might contribute almost nothing to real request latency, and vice versa.

2. Detecting Event Loop Lag

Week 1 established that Node runs your JavaScript on a single thread, with the event loop scheduling callbacks between I/O operations. Event loop lag is the delay between when a callback (a timer, an I/O completion) should run and when it actually gets a chance to — and a growing lag means something is monopolizing the thread and starving every other in-flight request, not just the one doing the expensive work.

import { monitorEventLoopDelay } from "node:perf_hooks";

const histogram = monitorEventLoopDelay({ resolution: 20 });
histogram.enable();

setInterval(() => {
  const p99Ms = histogram.percentile(99) / 1e6;   // nanoseconds -> ms
  if (p99Ms > 100) {
    logger.warn({ p99Ms }, "Event loop lag exceeded 100ms");
  }
  histogram.reset();
}, 10_000);

A synchronous, CPU-heavy operation — a large JSON payload being parsed, a big array being sorted, a regex with catastrophic backtracking — blocks the event loop for its entire duration, and everything else queued behind it (every other request's callbacks, every timer) simply waits. This is the same class of problem Week 9's async/await discussion warned about from a different angle: await only yields control at genuine I/O boundaries, and a synchronous CPU-bound function has no await point to yield at, no matter how it's wrapped.

3. Worker Threads for CPU-Bound Work

Node's built-in worker_threads module runs JavaScript on a genuinely separate OS thread, with its own V8 instance and its own event loop, isolated from the main thread's memory by default. This is Node's actual answer to CPU-bound work — not clustering (Week 14, which forks separate processes to use multiple cores for handling more concurrent requests), but a way to move one expensive, synchronous computation off the thread that's serving everyone else.

import { parentPort, workerData } from "node:worker_threads";

function renderReport(rows: unknown[]): Buffer {
  // CPU-heavy: aggregation + PDF rendering, no network or disk waiting involved
  const aggregated = summarize(rows);
  return renderPdf(aggregated);
}

const result = renderReport(workerData.rows);
parentPort!.postMessage(result);

import { Worker } from "node:worker_threads";

function generateReportOffThread(rows: unknown[]): Promise<Buffer> {
  return new Promise((resolve, reject) => {
    const worker = new Worker("./dist/workers/reportWorker.js", { workerData: { rows } });
    worker.once("message", resolve);
    worker.once("error", reject);
  });
}

While renderReport runs inside the worker, the main thread's event loop is completely free to keep handling every other request — the whole point of moving it off-thread in the first place. Data passed via workerData and postMessage is copied (or, for large binary data, can be efficiently transferred) between threads rather than shared directly, since JavaScript objects aren't safely shared across threads the way they can be read within one.

A worker pool (via a library like piscina, or hand-rolled) avoids the overhead of spinning up a fresh worker thread — genuinely expensive relative to the work itself — for every single request, reusing a fixed set of workers across many jobs instead.

4. Hands-on Exercise

5. Knowledge Check

Three quick questions. Expand each to check your answer.