Skip to content
Tutorials Center
My learning

Topics

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().

NODE
import { createHook } from 'node:async_hooks';

const hook = createHook({ init(id, type, trigger, resource) {} });
hook.enable();

Try it

Node.js Watching a timer being created and run

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.

Node.js Resource types and disabling

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

NODE
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 use fs.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, destroy or promiseResolve; 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.
  • destroy is unreliable for timing. It runs when the resource is collected, which can be long after the work ended.
  • Prefer AsyncLocalStorage for context, and diagnostics_channel or PerformanceObserver for observability.
  • Stability: async_hooks is documented as experimental except for AsyncLocalStorage, executionAsyncId() and triggerAsyncId().