Async Hooks in Node.js: A Complete Guide

1. Introduction

Async Hooks allow developers to track the lifecycle of asynchronous resources such as Promises, TCP connections, and timers. Each resource is assigned a unique asyncId that identifies it within the Node.js process.

2. Core API

const async_hooks = require('node:async_hooks');

// Current execution context ID
const eid = async_hooks.executionAsyncId();

// ID of the resource that triggered the current one
const tid = async_hooks.triggerAsyncId();

// Create a new hook
const hook = async_hooks.createHook({ init, before, after, destroy, promiseResolve });
hook.enable();
hook.disable();

3. Hook Callbacks

• init(asyncId, type, triggerAsyncId, resource): Called when a resource is initialized.
• before(asyncId): Called just before the resource’s callback executes.
• after(asyncId): Called immediately after the resource’s callback finishes.
• destroy(asyncId): Called when the resource is destroyed.
• promiseResolve(asyncId): Called when a Promise is resolved.

4. Error Handling

If any AsyncHook callback throws an error, Node.js prints the stack trace and exits. This strict behavior is due to the volatile nature of object lifecycles during construction and destruction.

5. Debugging Notes

Using console.log() inside AsyncHook callbacks causes infinite recursion because logging itself is asynchronous. Instead, use synchronous logging like fs.writeFileSync() for debugging.

const fs = require('node:fs');
const util = require('node:util');

function debug(...args) {
  fs.writeFileSync('log.out', `${util.format(...args)}\n`, { flag: 'a' });
}

6. The AsyncHook Class

The AsyncHook class exposes an interface for tracking lifecycle events of asynchronous operations. Hooks are disabled by default and must be explicitly enabled.

const async_hooks = require('node:async_hooks');
const hook = async_hooks.createHook(callbacks).enable();

7. Example: TCP Server Tracking

This example demonstrates tracking events in a TCP server:

const async_hooks = require('node:async_hooks');
const fs = require('node:fs');
const net = require('node:net');
const { fd } = process.stdout;

let indent = 0;
async_hooks.createHook({
  init(asyncId, type, triggerAsyncId) {
    const eid = async_hooks.executionAsyncId();
    fs.writeSync(fd, `${' '.repeat(indent)}${type}(${asyncId}): trigger: ${triggerAsyncId} execution: ${eid}\n`);
  },
  before(asyncId) {
    fs.writeSync(fd, `${' '.repeat(indent)}before: ${asyncId}\n`);
    indent += 2;
  },
  after(asyncId) {
    indent -= 2;
    fs.writeSync(fd, `${' '.repeat(indent)}after: ${asyncId}\n`);
  },
  destroy(asyncId) {
    fs.writeSync(fd, `${' '.repeat(indent)}destroy: ${asyncId}\n`);
  },
}).enable();

net.createServer(() => {}).listen(8080);

8. executionAsyncId vs triggerAsyncId

• executionAsyncId(): Shows the context in which a resource was created.
• triggerAsyncId: Shows which resource triggered the creation of the new resource.

Conclusion

Although async_hooks is experimental and discouraged for production use, it provides valuable insight into the lifecycle of asynchronous resources in Node.js. For context tracking, developers should prefer AsyncLocalStorage, which is stable and safer.

1. before(asyncId)

Called just before the callback of an asynchronous resource executes. asyncId is the unique identifier of the resource. This hook may be called 0 to N times:

• Persistent resources like TCP servers call before multiple times.
• One-off operations like fs.open() call it only once.

2. after(asyncId)

Called immediately after the callback specified in before completes. Even if an uncaught exception occurs, after runs once the exception is emitted.

3. destroy(asyncId)

Called when the resource is destroyed. If the resource relies on garbage collection, destroy may never be called, potentially causing memory leaks. Tracking destroy hooks adds overhead because it enables Promise tracking via the garbage collector.

4. promiseResolve(asyncId)

Called when the resolve() function of a Promise is invoked. This does not mean the Promise is fulfilled or rejected yet, only that resolution has been triggered.

new Promise((resolve) => resolve(true)).then(() => {});
// Calls: init, promiseResolve, before, after

5. executionAsyncResource()

Returns the resource representing the current execution. Typically, this is an internal Node.js handle object. Accessing undocumented properties may crash the application.

Example:

const { open } = require('node:fs');
const { executionAsyncId, executionAsyncResource } = require('node:async_hooks');

console.log(executionAsyncId(), executionAsyncResource()); // 1 {}
open(__filename, 'r', (err, fd) => {
  console.log(executionAsyncId(), executionAsyncResource()); // 7 FSReqWrap
});

6. executionAsyncId()

Returns the asyncId of the current execution context. This ID reflects execution timing, not causality.

const async_hooks = require('node:async_hooks');
console.log(async_hooks.executionAsyncId()); // 1 bootstrap

7. triggerAsyncId()

Returns the ID of the resource that triggered the current callback.

const server = net.createServer((conn) => {
  async_hooks.triggerAsyncId(); // ID of the connection
}).listen(port);

8. asyncWrapProviders

Introduced in v17.2.0, this returns a map of provider types to numeric IDs. It replaces the deprecated process.binding('async_wrap').Providers.

9. Promise Execution Tracking

By default, Promises do not receive asyncIds due to performance costs. Enabling hooks forces Promise tracking.

const { createHook, executionAsyncId, triggerAsyncId } = require('node:async_hooks');

createHook({ init() {} }).enable();
Promise.resolve(1729).then(() => {
  console.log(`eid ${executionAsyncId()} tid ${triggerAsyncId()}`);
});

In this example, the first Promise gets asyncId=6 and the chained Promise gets asyncId=7.

Conclusion

The before, after, destroy, and promiseResolve hooks provide detailed tracking of asynchronous resource lifecycles. Methods like executionAsyncResource, executionAsyncId, and triggerAsyncId are essential for identifying execution contexts and triggers. Although async_hooks is experimental and discouraged for production use, it remains a valuable tool for understanding Node.js asynchronous behavior.