Question
async_hooks vs AsyncLocalStorage: Memory leak risk vs diagnostic control
Sky Moss
0 reputation · 25 Nov 2024, 08:11 UTC
133.2K views1
Loading…
0 reputation · 25 Nov 2024, 08:11 UTC
Node.js offers two documented mechanisms for tracking async context: the low-level async_hooks API and the higher-level AsyncLocalStorage. Both rely on the same async resource model, but they differ sharply in memory behavior. async_hooks exposes granular lifecycle events, enabling custom propagation and deep diagnostics, but it is marked experimental (Stability 1) and requires manual destroy handling; forgetting to call destroy on custom resources can retain references and cause unbounded memory growth. AsyncLocalStorage, stable since Node 13, automatically associates and cleans up stores, reducing leak risk, but it hides the fine-grained event details needed for advanced tracing.
The unresolved decision is when direct async_hooks usage is justified despite the overhead and leak potential. There is no formal guidance on the exact memory retention semantics when async_hooks is enabled without a destroy hook, and behavior varies across Node versions.
What criteria should drive the choice between async_hooks and AsyncLocalStorage for a production service? Is there a documented pattern for safely using async_hooks without leaking, or is AsyncLocalStorage always the recommended default?
For most production services, AsyncLocalStorage is the safe default because it automatically manages store lifecycle and minimizes leak risk. Use raw async_hooks only when you need fine‑grained lifecycle diagnostics (e.g., measuring the duration of each async resource or building a custom APM) and you can guarantee proper cleanup.
nodejsAsyncLocalStorage is a stable wrapper (Node ≥ 13.10) that creates a store per async context and clears it on destroy.async_hooks API emits init, before, after, and destroy events for every asynchronous resource.asyncId in the init hook and never delete it in destroy, the map grows unboundedly, causing a memory leak.async_hooks because its hooks run on every async transition.AsyncLocalStorage for request‑scoped data.async_hooks with a strict destroy hook that removes any data stored for the asyncId.--inspect and use Chrome DevTools to take heap snapshots before and after a load test; look for growing maps keyed by asyncId.node --inspect your-service.js
# Then open chrome://inspect and profile memory.Missing Diagnostic Detail: Are you trying to measure the lifetime or duration of individual asynchronous resources, or merely propagate a request identifier?
Use comments to ask for clarification. Post a solution as an answer.
5,960 reputation · 25 Nov 2024, 09:56 UTC
While memory leaks are a primary concern, the CPU overhead of async_hooks is a critical deciding factor for production services. Because async_hooks executes the init and destroy callbacks for every asynchronous resource created across the entire Node.js process—including internal timers and network sockets—the performance penalty is global, not just limited to the tracked context.
To determine if AsyncLocalStorage is sufficient or if async_hooks is necessary, consider these verification steps:
--inspect flag and Chrome DevTools to monitor for unbounded growth in Map objects when using custom async_hooks logic.