Even with sufficient CPU and RAM, a Node.js application may still react slowly to queries. The database or an external API may not always be the issue. The program is stalling its own event loop for an excessive amount of time.
An event loop is used by Node.js to manage timers, callbacks, asynchronous activities, and JavaScript execution. Other callbacks must wait until the event loop has completed a lengthy job.
We refer to this delay as event loop lag. An otherwise healthy program may seem sluggish due to high event loop lag, which can also raise request latency and delay times. The good news is that you can measure event loop lag directly and use the results to identify expensive synchronous operations, CPU-heavy JavaScript, and other sources of delay. In this article, you will learn how event loop lag works, how to measure it in Node.js, how to find its cause, and how to reduce it without blindly adding more servers.
What Is Event Loop Lag?
The Node.js event loop processes JavaScript callbacks and coordinates many asynchronous operations. It allows a single JavaScript thread to manage numerous connections without creating a separate JavaScript thread for every request.
However, JavaScript running on the main thread still executes one callback at a time. While a long-running callback is executing, other callbacks cannot run on that thread.
Consider this example:
function processRequest() {
const start = Date.now();
while (Date.now() - start < 3000) {
// Simulate CPU-intensive synchronous work.
}
console.log("Processing completed");
}
processRequest();
This function blocks the JavaScript thread for approximately three seconds.
During that time, other JavaScript callbacks on the same event loop cannot execute. Incoming connections may wait, timers may fire late, and completed asynchronous operations may have their callbacks delayed.
Event loop lag measures how much later the event loop runs scheduled work than expected.
It is different from request latency. A request can be slow because it is waiting for a database, even when event loop lag is low. Conversely, a request may experience additional delay because the event loop is blocked by unrelated work.
Understanding this difference helps you identify the actual bottleneck.
Why Event Loop Lag Matters
Event loop lag affects more than one request.
1. Slow API Responses
Suppose an API normally responds in 100 milliseconds. If a CPU-heavy callback blocks the event loop for one second, requests that need JavaScript execution may experience substantial additional delay.
Even requests that depend on fast database queries can become slow because their callbacks cannot run promptly.
2. Delayed Timers
Timers scheduled with setTimeout() and setInterval() are not guaranteed to execute at an exact time.
If the event loop is busy, their callbacks run later than expected.
This can affect polling loops, scheduled cleanup, retry logic, and background tasks that run inside the Node.js process.
3. Reduced Throughput
When the main thread spends too much time on expensive synchronous work, it has less time available to process other callbacks.
The application may handle fewer requests per second even when network and database resources are available.
4. Unreliable Real-Time Features
Applications using WebSockets, streaming responses, or other real-time communication can become less responsive when event loop lag rises.
Messages may be delayed because the JavaScript callbacks responsible for processing or sending them cannot run on time.
Step 1: Measure Event Loop Delay with Node.js
Node.js provides the built-in monitorEventLoopDelay() function in the node:perf_hooks module.
It uses a histogram to measure delays between expected and actual timer execution.
const {
monitorEventLoopDelay
} = require("node:perf_hooks");
const histogram = monitorEventLoopDelay({
resolution: 20
});
histogram.enable();
setInterval(() => {
console.log({
minMs: histogram.min / 1e6,
maxMs: histogram.max / 1e6,
meanMs: histogram.mean / 1e6,
p99Ms: histogram.percentile(99) / 1e6
});
histogram.reset();
}, 10000);
How This Code Works
The monitorEventLoopDelay() function creates a histogram that records event loop delay.
The resolution option controls the approximate sampling interval in milliseconds. A value of 20 requests sampling at roughly 20-millisecond intervals.
The histogram reports values in nanoseconds, so the code divides each measurement by one million to convert it to milliseconds.
The reported metrics mean:
- minMs: Minimum observed delay during the measurement window.
- maxMs: Maximum observed delay.
- meanMs: Average observed delay.
- p99Ms: The 99th percentile delay, meaning approximately 99% of recorded delays were at or below this value.
The interval resets the histogram after reporting so that the next report focuses on a new measurement window.
This is useful for basic monitoring, but it is not a complete observability solution. In production, export these measurements to your metrics system and interpret them alongside request latency, CPU usage, and throughput.
Also, histogram values depend on sampling resolution, workload, and the measurement window. Establish a baseline before deciding which values should trigger alerts.
Step 2: Understand the Difference Between Event Loop Delay and Utilization
Event loop delay and event loop utilization measure related but different things.
Event loop delay measures how late scheduled event loop activity occurs.
Event loop utilization (ELU) measures the proportion of time the event loop spends outside its idle state over a measurement interval, according to Node.js's event loop utilization metric.
You can measure ELU with performance.eventLoopUtilization().
const {
performance
} = require("node:perf_hooks");
let previous = performance.eventLoopUtilization();
setInterval(() => {
const current = performance.eventLoopUtilization();
const interval = performance.eventLoopUtilization(
current,
previous
);
previous = current;
console.log({
utilization: interval.utilization,
activeMs: interval.active,
idleMs: interval.idle
});
}, 10000);
The utilization value is between 0 and 1. A value close to 1 indicates that the event loop spent most of the measured interval in its active state.
High utilization does not automatically mean the application is unhealthy. A busy application can have high utilization while still meeting its latency requirements.
Likewise, event loop delay may increase during a short blocking operation even if average utilization over a longer interval appears acceptable.
Use both metrics to understand how busy the event loop is and whether callbacks are being delayed.
Step 3: Find CPU-Heavy JavaScript
One common cause of high event loop lag is CPU-intensive synchronous JavaScript.
Examples include:
- Processing large arrays in one callback.
- Parsing or serializing very large JSON documents.
- Performing expensive calculations.
- Running complex regular expressions on large inputs.
- Compressing data synchronously.
- Executing large loops inside request handlers.
For example:
app.post("/process", (req, res) => {
const result = expensiveCalculation(req.body);
res.json(result);
});
If expensiveCalculation() takes several seconds on the main thread, other requests may be delayed while it runs.
Start by measuring the duration of the operation.
const { performance } = require("node:perf_hooks");
function measureCalculation(input) {
const start = performance.now();
const result = expensiveCalculation(input);
const durationMs = performance.now() - start;
console.log({
operation: "expensiveCalculation",
durationMs
});
return result;
}
This example measures how long the function takes. It does not solve the blocking problem, but it helps identify expensive operations.
For deeper analysis, use a CPU profile to inspect which functions consume the most CPU time.
Avoid logging every operation in a high-traffic application without considering the overhead. Use sampling, structured metrics, or a profiler when appropriate.
Step 4: Use the Node.js CPU Profiler
A CPU profile helps you understand where the JavaScript thread spends its execution time.
You can start Node.js with the built-in CPU profiling option:
node --cpu-prof app.js
After the process exits, Node.js writes a CPU profile file. You can inspect the profile in a compatible developer tool to identify expensive functions and call paths.
For an existing process, you can also use supported inspector-based profiling tools, provided that access to the inspector is secured.
When reviewing a CPU profile, look for:
- Functions with high self time.
- Functions with high total time.
- Repeated calls to expensive operations.
- Large amounts of JSON processing.
- Unexpected synchronous filesystem or cryptographic work.
- Application code spending significant time in loops or transformations.
Self time represents time spent directly in a function, while total time includes time spent in functions called by it.
A function with low self time can still be responsible for significant cost if it repeatedly calls an expensive function.
CPU profiling is particularly useful when event loop lag increases during real traffic but the responsible code path is not obvious.
Step 5: Move CPU-Heavy Work Off the Main Thread
If profiling identifies a CPU-heavy operation, consider moving it to a worker thread or a separate processing service.
Node.js provides the node:worker_threads module for running JavaScript in additional threads.
Worker threads are useful for CPU-intensive JavaScript that can operate independently of the main event loop.
For example, a worker can perform a large calculation while the main thread continues processing other callbacks.
However, moving work to a worker thread introduces communication and lifecycle overhead. The data sent to the worker may need to be cloned or transferred, and excessive worker creation can consume resources.
For recurring jobs, a worker pool is often more practical than creating a new worker for every request.
Also consider whether the task can be handled by a separate background queue or service. That approach can provide better isolation when the operation is large, slow, or needs independent scaling.
Step 6: Investigate Synchronous I/O and Large Payloads
CPU-heavy JavaScript is not the only possible cause of event loop lag.
Synchronous filesystem calls, synchronous child-process operations, and other blocking APIs can prevent the main thread from processing callbacks.
For example:
const fs = require("node:fs");
function readConfiguration() {
return fs.readFileSync(
"./config.json",
"utf8"
);
}
This call blocks JavaScript execution until the file operation completes.
For operations that can use asynchronous APIs, consider an asynchronous alternative:
const fs = require("node:fs/promises");
async function readConfiguration() {
return fs.readFile(
"./config.json",
"utf8"
);
}
The asynchronous version allows the event loop to process other work while the filesystem operation is pending. However, asynchronous APIs do not make every operation free of CPU cost. Parsing a very large JSON document after reading it still runs JavaScript on the main thread unless you deliberately move that work elsewhere.
The same principle applies to large request payloads. Validate input size, avoid unnecessary transformations, and consider streaming when the application does not need to hold the entire payload in memory.
Step 7: Correlate Event Loop Lag with API Metrics
Event loop lag is most useful when combined with application-level measurements.
Monitor these metrics together:
|
Metric
|
What It Helps Identify
|
|
Event loop delay
|
Late execution of scheduled event loop activity
|
|
Event loop utilization
|
How busy the event loop is
|
|
Request latency
|
How long API requests take
|
|
Requests per second
|
Application throughput
|
|
CPU usage
|
Overall process or container CPU pressure
|
|
Heap usage
|
JavaScript memory consumption
|
|
Database latency
|
Time spent waiting for database operations
|
|
Error rate
|
Failures associated with slow or overloaded processing
|
For example, if event loop delay and CPU usage rise together while request latency increases, CPU-heavy JavaScript is a reasonable place to investigate. If request latency rises while event loop delay remains low, the bottleneck may instead be the database, an external API, network latency, or another asynchronous dependency. These patterns are clues, not definitive proof. Use traces, logs, and profiling data to confirm the cause.
Common Mistakes to Avoid
- Assuming all slow requests are caused by the event loop: Database and network delays can produce slow responses without high event loop lag.
- Monitoring only average delay: Short but severe spikes can be hidden by averages.
- Treating high utilization as a failure by itself: High utilization must be interpreted against latency and throughput requirements.
- Using asynchronous APIs as a complete solution: CPU-heavy callbacks can still block the event loop after asynchronous I/O finishes.
- Creating too many worker threads: Excessive parallelism can increase CPU contention and memory usage.
- Measuring only in development: Production traffic and payload sizes may expose problems that small test workloads do not.
- Exposing the Node.js inspector publicly: Profiling endpoints can provide powerful access to the running process.
Best Practices for Keeping Event Loop Lag Low
- Measure event loop delay and utilization continuously.
- Establish thresholds based on the application's latency requirements.
- Use CPU profiles to find expensive JavaScript functions.
- Avoid synchronous I/O in request-handling paths.
- Break large operations into smaller chunks when practical.
- Use worker threads or background jobs for CPU-intensive work.
- Limit request payload sizes and avoid unnecessary data transformations.
- Correlate event loop metrics with traces, database latency, and error rates.
- Test performance using representative workloads before deploying optimizations.
Conclusion
Node.js event loop lag is an important signal when investigating slow APIs and unresponsive applications. It measures delays in scheduled event loop activity and helps identify cases where the JavaScript thread cannot process callbacks promptly. Start by measuring event loop delay with monitorEventLoopDelay() and event loop utilization with performance.eventLoopUtilization(). Then use CPU profiling, operation-level timing, and application metrics to locate the underlying cause.
If synchronous work is blocking the event loop, optimize the operation, move suitable CPU-intensive work to worker threads, or process it in a separate service. The goal is not to keep event loop utilization as low as possible. It is to ensure that the application processes callbacks promptly and consistently meets its latency and throughput requirements.