What use cases exist for async_hooks?

2 min readJul 15, 2021


Hello, Node.js users! 👋

The Diagnostics working group is looking for feedback on what ways Node.js users are using the async_hooks API and to elaborate on exactly what about that problem makes async_hooks useful for them. We hope to build higher-level abstractions more purpose-built for the needs of our users. Unfortunately, due to async_hooks leaking internals and being a generally confusing API, we do not see a good path forward to moving async_hooks out of "experimental" status so we are seeking input on alternatives to better serve those needs.

Over the years there have been several iterations of APIs providing low-level insight into the lifecycle of async execution in Node.js. Unfortunately, all of them have suffered from leaking internals in some way or another which has led to them getting stuck in “experimental” status limbo forever. Over the last year and a half there has been some effort to create higher-level abstractions on top of it to solve specific use-cases, most notably AsyncLocalStorage to propagate a storage object through the async call graph and serve as a request context to pass data around within HTTP requests. This new interface has eliminated a significant use case for async_hooks but other use cases remain.

Other use cases we are already considering are:

  • long stack traces
    - can produce more meaningful error information
    - helpful for debugging complex async execution chains
  • lifecycle tracking of libuv requests/handles
    - helps detect resource starvation
    - could probably provide some meta information to differentiate requests/handles
  • detecting blocking code
    - measuring sync execution time of each callback
    - helps to identify code that could be moved to worker threads
  • counting created promises
  • detecting port of new servers without monkey-patching

Due to the low-level nature of the async_hooks API there are many ways it can be used. However, it can also be quite difficult to use safely and can be quite awkward or slow depending on what you are trying to do. If we can gather more feedback on what people are using it for, we can use that to guide design of better-suited APIs at a level of abstraction that leaves us more power to rearrange the internals in ways that would be more performant without worrying about breaking existing users like we do with async_hooks currently.

We would appreciate if you would share any use cases you have for async_hooks at: https://github.com/nodejs/diagnostics/issues/437




Node.js is a collaborative open source project dedicated to building and supporting the Node.js platform. https://nodejs.org/en/