Node.js Reference ยท node:sqlite and Runtime Services
Node.js async_hooks.createHook() function
Reference for async_hooks.createHook(): the init, before, after, destroy and promiseResolve callbacks, enable() and disable(), and the logging pitfalls.
createHook() registers callbacks that Node calls during the lifecycle of every asynchronous resource: timers, promises, sockets, file operations and more. A resource gets an init call when it is created, before and after calls around each time its callback runs, promiseResolve for promises, and destroy when it is gone. Each resource has a numeric async id.
It is a low-level diagnostic tool, used by profilers and tracing libraries. For passing request data through async code, AsyncLocalStorage is the better and cheaper choice. Hooks are only active between enable() and disable().
import { createHook } from 'node:async_hooks'; const hook = createHook({ init(id, type, trigger, resource) {} }); hook.enable();
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
createHook(callbacks: { init?(asyncId: number, type: string, triggerAsyncId: number, resource: object): void, before?(asyncId: number): void, after?(asyncId: number): void, destroy?(asyncId: number): void, promiseResolve?(asyncId: number): void, }): AsyncHook hook.enable(): AsyncHook hook.disable(): AsyncHook
| Callback | When it runs |
|---|---|
init |
A resource is created. type names it (Timeout, TCPWRAP, PROMISE, ...); triggerAsyncId is the execution that caused it; resource is the underlying object. |
before |
Just before the resource's callback runs. May run many times for repeating resources like intervals. |
after |
Just after the callback finishes. If the callback throws, it is called after the uncaught-exception handlers. |
destroy |
The resource has been destroyed. May be delayed until garbage collection. |
promiseResolve |
resolve() was called on a promise (not necessarily the moment it settles in its chain). |
Returns: an AsyncHook with enable() and disable(), both returning the hook.
Errors: a TypeError (ERR_ASYNC_CALLBACK) if a provided callback is not a function.
Usage notes
- Do not call
console.log()inside a callback. Writing to the console creates new async resources, which call the hook again, and so on until the process crashes. Collect data in memory, or usefs.writeSync(1, ...), which is synchronous. - Hooks are global and add overhead to every async operation while enabled. Do not leave them on in production without measuring.
- Promises are only tracked when a hook is enabled that has
init,before,after,destroyorpromiseResolve; enabling a hook changes timing slightly. - Async ids are numbers unique within a process, not stable between runs. Never print them in tests; compare them with each other.
- Do not throw from callbacks. An error in a hook is fatal and the process exits.
destroyis unreliable for timing. It runs when the resource is collected, which can be long after the work ended.- Prefer
AsyncLocalStoragefor context, anddiagnostics_channelorPerformanceObserverfor observability. - Stability:
async_hooksis documented as experimental except forAsyncLocalStorage,executionAsyncId()andtriggerAsyncId().