Terminology#

An asynchronous resource represents an object with an associated callback.This callback may be called multiple times, such as the'connection'event innet.createServer(), or just a single time like infs.open().A resource can also be closed before the callback is called.AsyncHook doesnot explicitly distinguish between these different cases but will represent themas the abstract concept that is a resource.

IfWorkers are used, each thread has an independentasync_hooksinterface, and each thread will use a new set of async IDs.

Overview#

Following is a simple overview of the public API.

import async_hooksfrom'node:async_hooks';// Return the ID of the current execution context.const eid = async_hooks.executionAsyncId();// Return the ID of the handle responsible for triggering the callback of the// current execution scope to call.const tid = async_hooks.triggerAsyncId();// Create a new AsyncHook instance. All of these callbacks are optional.const asyncHook =    async_hooks.createHook({ init, before, after, destroy, promiseResolve });// Allow callbacks of this AsyncHook instance to call. This is not an implicit// action after running the constructor, and must be explicitly run to begin// executing callbacks.asyncHook.enable();// Disable listening for new asynchronous events.asyncHook.disable();//// The following are the callbacks that can be passed to createHook().//// init() is called during object construction. The resource may not have// completed construction when this callback runs. Therefore, all fields of the// resource referenced by "asyncId" may not have been populated.functioninit(asyncId, type, triggerAsyncId, resource) { }// before() is called just before the resource's callback is called. It can be// called 0-N times for handles (such as TCPWrap), and will be called exactly 1// time for requests (such as FSReqCallback).functionbefore(asyncId) { }// after() is called just after the resource's callback has finished.functionafter(asyncId) { }// destroy() is called when the resource is destroyed.functiondestroy(asyncId) { }// promiseResolve() is called only for promise resources, when the// resolve() function passed to the Promise constructor is invoked// (either directly or through other means of resolving a promise).functionpromiseResolve(asyncId) { }const async_hooks =require('node:async_hooks');// Return the ID of the current execution context.const eid = async_hooks.executionAsyncId();// Return the ID of the handle responsible for triggering the callback of the// current execution scope to call.const tid = async_hooks.triggerAsyncId();// Create a new AsyncHook instance. All of these callbacks are optional.const asyncHook =    async_hooks.createHook({ init, before, after, destroy, promiseResolve });// Allow callbacks of this AsyncHook instance to call. This is not an implicit// action after running the constructor, and must be explicitly run to begin// executing callbacks.asyncHook.enable();// Disable listening for new asynchronous events.asyncHook.disable();//// The following are the callbacks that can be passed to createHook().//// init() is called during object construction. The resource may not have// completed construction when this callback runs. Therefore, all fields of the// resource referenced by "asyncId" may not have been populated.functioninit(asyncId, type, triggerAsyncId, resource) { }// before() is called just before the resource's callback is called. It can be// called 0-N times for handles (such as TCPWrap), and will be called exactly 1// time for requests (such as FSReqCallback).functionbefore(asyncId) { }// after() is called just after the resource's callback has finished.functionafter(asyncId) { }// destroy() is called when the resource is destroyed.functiondestroy(asyncId) { }// promiseResolve() is called only for promise resources, when the// resolve() function passed to the Promise constructor is invoked// (either directly or through other means of resolving a promise).functionpromiseResolve(asyncId) { }copy

async_hooks.createHook(callbacks)#

• callbacks<Object> TheHook Callbacks to register
  • init<Function> Theinit callback.
  • before<Function> Thebefore callback.
  • after<Function> Theafter callback.
  • destroy<Function> Thedestroy callback.
  • promiseResolve<Function> ThepromiseResolve callback.
• Returns:<AsyncHook> Instance used for disabling and enabling hooks

Registers functions to be called for different lifetime events of each asyncoperation.

The callbacksinit()/before()/after()/destroy() are called for therespective asynchronous event during a resource's lifetime.

All callbacks are optional. For example, if only resource cleanup needs tobe tracked, then only thedestroy callback needs to be passed. Thespecifics of all functions that can be passed tocallbacks is in theHook Callbacks section.

import { createHook }from'node:async_hooks';const asyncHook =createHook({init(asyncId, type, triggerAsyncId, resource) { },destroy(asyncId) { },});const async_hooks =require('node:async_hooks');const asyncHook = async_hooks.createHook({init(asyncId, type, triggerAsyncId, resource) { },destroy(asyncId) { },});copy

The callbacks will be inherited via the prototype chain:

classMyAsyncCallbacks {init(asyncId, type, triggerAsyncId, resource) { }destroy(asyncId) {}}classMyAddedCallbacksextendsMyAsyncCallbacks {before(asyncId) { }after(asyncId) { }}const asyncHook = async_hooks.createHook(newMyAddedCallbacks());copy

Because promises are asynchronous resources whose lifecycle is trackedvia the async hooks mechanism, theinit(),before(),after(), anddestroy() callbacksmust not be async functions that return promises.

import { writeFileSync }from'node:fs';import { format }from'node:util';functiondebug(...args) {// Use a function like this one when debugging inside an AsyncHook callbackwriteFileSync('log.out',`${format(...args)}\n`, {flag:'a' });}const fs =require('node:fs');const util =require('node:util');functiondebug(...args) {// Use a function like this one when debugging inside an AsyncHook callback  fs.writeFileSync('log.out',`${util.format(...args)}\n`, {flag:'a' });}copy

Class:AsyncHook#

The classAsyncHook exposes an interface for tracking lifetime eventsof asynchronous operations.

import { createHook }from'node:async_hooks';const hook =createHook(callbacks).enable();const async_hooks =require('node:async_hooks');const hook = async_hooks.createHook(callbacks).enable();copy

import { createServer }from'node:net';createServer().listen(function() {this.close(); });// ORclearTimeout(setTimeout(() => {},10));require('node:net').createServer().listen(function() {this.close(); });// ORclearTimeout(setTimeout(() => {},10));copy

import { createHook, executionAsyncId }from'node:async_hooks';import { stdout }from'node:process';import netfrom'node:net';import fsfrom'node:fs';createHook({init(asyncId, type, triggerAsyncId) {const eid =executionAsyncId();    fs.writeSync(      stdout.fd,`${type}(${asyncId}): trigger:${triggerAsyncId} execution:${eid}\n`);  },}).enable();net.createServer((conn) => {}).listen(8080);const { createHook, executionAsyncId } =require('node:async_hooks');const { stdout } =require('node:process');const net =require('node:net');const fs =require('node:fs');createHook({init(asyncId, type, triggerAsyncId) {const eid =executionAsyncId();    fs.writeSync(      stdout.fd,`${type}(${asyncId}): trigger:${triggerAsyncId} execution:${eid}\n`);  },}).enable();net.createServer((conn) => {}).listen(8080);copy

TCPSERVERWRAP(5): trigger: 1 execution: 1TCPWRAP(7): trigger: 5 execution: 0copy

import async_hooksfrom'node:async_hooks';import fsfrom'node:fs';import netfrom'node:net';import { stdout }from'node:process';const { fd } = stdout;let indent =0;async_hooks.createHook({init(asyncId, type, triggerAsyncId) {const eid = async_hooks.executionAsyncId();const indentStr =' '.repeat(indent);    fs.writeSync(      fd,`${indentStr}${type}(${asyncId}):` +` trigger:${triggerAsyncId} execution:${eid}\n`);  },before(asyncId) {const indentStr =' '.repeat(indent);    fs.writeSync(fd,`${indentStr}before:${asyncId}\n`);    indent +=2;  },after(asyncId) {    indent -=2;const indentStr =' '.repeat(indent);    fs.writeSync(fd,`${indentStr}after:${asyncId}\n`);  },destroy(asyncId) {const indentStr =' '.repeat(indent);    fs.writeSync(fd,`${indentStr}destroy:${asyncId}\n`);  },}).enable();net.createServer(() => {}).listen(8080,() => {// Let's wait 10ms before logging the server started.setTimeout(() => {console.log('>>>', async_hooks.executionAsyncId());  },10);});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();const indentStr =' '.repeat(indent);    fs.writeSync(      fd,`${indentStr}${type}(${asyncId}):` +` trigger:${triggerAsyncId} execution:${eid}\n`);  },before(asyncId) {const indentStr =' '.repeat(indent);    fs.writeSync(fd,`${indentStr}before:${asyncId}\n`);    indent +=2;  },after(asyncId) {    indent -=2;const indentStr =' '.repeat(indent);    fs.writeSync(fd,`${indentStr}after:${asyncId}\n`);  },destroy(asyncId) {const indentStr =' '.repeat(indent);    fs.writeSync(fd,`${indentStr}destroy:${asyncId}\n`);  },}).enable();net.createServer(() => {}).listen(8080,() => {// Let's wait 10ms before logging the server started.setTimeout(() => {console.log('>>>', async_hooks.executionAsyncId());  },10);});copy

TCPSERVERWRAP(5): trigger: 1 execution: 1TickObject(6): trigger: 5 execution: 1before:  6  Timeout(7): trigger: 6 execution: 6after:   6destroy: 6before:  7>>> 7  TickObject(8): trigger: 7 execution: 7after:   7before:  8after:   8copy

  root(1)     ^     |TickObject(6)     ^     | Timeout(7)copy

 bootstrap(1)     |     ˅TCPSERVERWRAP(5)     |     ˅ TickObject(6)     |     ˅  Timeout(7)copy

newPromise((resolve) =>resolve(true)).then((a) => {});copy

init for PROMISE with id 5, trigger id: 1  promise resolve 5      # corresponds to resolve(true)init for PROMISE with id 6, trigger id: 5  # the Promise returned by then()  before 6               # the then() callback is entered  promise resolve 6      # the then() callback resolves the promise by returning  after 6copy

import { open }from'node:fs';import { executionAsyncId, executionAsyncResource }from'node:async_hooks';console.log(executionAsyncId(),executionAsyncResource());// 1 {}open(newURL(import.meta.url),'r',(err, fd) => {console.log(executionAsyncId(),executionAsyncResource());// 7 FSReqWrap});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});copy

import { createServer }from'node:http';import {  executionAsyncId,  executionAsyncResource,  createHook,}from'node:async_hooks';const sym =Symbol('state');// Private symbol to avoid pollutioncreateHook({init(asyncId, type, triggerAsyncId, resource) {const cr =executionAsyncResource();if (cr) {      resource[sym] = cr[sym];    }  },}).enable();const server =createServer((req, res) => {executionAsyncResource()[sym] = {state: req.url };setTimeout(function() {    res.end(JSON.stringify(executionAsyncResource()[sym]));  },100);}).listen(3000);const { createServer } =require('node:http');const {  executionAsyncId,  executionAsyncResource,  createHook,} =require('node:async_hooks');const sym =Symbol('state');// Private symbol to avoid pollutioncreateHook({init(asyncId, type, triggerAsyncId, resource) {const cr =executionAsyncResource();if (cr) {      resource[sym] = cr[sym];    }  },}).enable();const server =createServer((req, res) => {executionAsyncResource()[sym] = {state: req.url };setTimeout(function() {    res.end(JSON.stringify(executionAsyncResource()[sym]));  },100);}).listen(3000);copy

import { executionAsyncId }from'node:async_hooks';import fsfrom'node:fs';console.log(executionAsyncId());// 1 - bootstrapconst path ='.';fs.open(path,'r',(err, fd) => {console.log(executionAsyncId());// 6 - open()});const async_hooks =require('node:async_hooks');const fs =require('node:fs');console.log(async_hooks.executionAsyncId());// 1 - bootstrapconst path ='.';fs.open(path,'r',(err, fd) => {console.log(async_hooks.executionAsyncId());// 6 - open()});copy

const server = net.createServer((conn) => {// Returns the ID of the server, not of the new connection, because the// callback runs in the execution scope of the server's MakeCallback().  async_hooks.executionAsyncId();}).listen(port,() => {// Returns the ID of a TickObject (process.nextTick()) because all// callbacks passed to .listen() are wrapped in a nextTick().  async_hooks.executionAsyncId();});copy

const server = net.createServer((conn) => {// The resource that caused (or triggered) this callback to be called// was that of the new connection. Thus the return value of triggerAsyncId()// is the asyncId of "conn".  async_hooks.triggerAsyncId();}).listen(port,() => {// Even though all callbacks passed to .listen() are wrapped in a nextTick()// the callback itself exists because the call to the server's .listen()// was made. So the return value would be the ID of the server.  async_hooks.triggerAsyncId();});copy

Promise execution tracking#

By default, promise executions are not assignedasyncIds due to the relativelyexpensive nature of thepromise introspection API provided byV8. This means that programs using promises orasync/await will not getcorrect execution and trigger ids for promise callback contexts by default.

import { executionAsyncId, triggerAsyncId }from'node:async_hooks';Promise.resolve(1729).then(() => {console.log(`eid${executionAsyncId()} tid${triggerAsyncId()}`);});// produces:// eid 1 tid 0const { executionAsyncId, triggerAsyncId } =require('node:async_hooks');Promise.resolve(1729).then(() => {console.log(`eid${executionAsyncId()} tid${triggerAsyncId()}`);});// produces:// eid 1 tid 0copy

Observe that thethen() callback claims to have executed in the context of theouter scope even though there was an asynchronous hop involved. Also,thetriggerAsyncId value is0, which means that we are missing context aboutthe resource that caused (triggered) thethen() callback to be executed.

Installing async hooks viaasync_hooks.createHook enables promise executiontracking:

import { createHook, executionAsyncId, triggerAsyncId }from'node:async_hooks';createHook({init() {} }).enable();// forces PromiseHooks to be enabled.Promise.resolve(1729).then(() => {console.log(`eid${executionAsyncId()} tid${triggerAsyncId()}`);});// produces:// eid 7 tid 6const { createHook, executionAsyncId, triggerAsyncId } =require('node:async_hooks');createHook({init() {} }).enable();// forces PromiseHooks to be enabled.Promise.resolve(1729).then(() => {console.log(`eid${executionAsyncId()} tid${triggerAsyncId()}`);});// produces:// eid 7 tid 6copy

In this example, adding any actual hook function enabled the tracking ofpromises. There are two promises in the example above; the promise created byPromise.resolve() and the promise returned by the call tothen(). In theexample above, the first promise got theasyncId6 and the latter gotasyncId7. During the execution of thethen() callback, we are executingin the context of promise withasyncId7. This promise was triggered byasync resource6.

Another subtlety with promises is thatbefore andafter callbacks are runonly on chained promises. That means promises not created bythen()/catch()will not have thebefore andafter callbacks fired on them. For more detailssee the details of the V8PromiseHooks API.

JavaScript embedder API#

Library developers that handle their own asynchronous resources performing taskslike I/O, connection pooling, or managing callback queues may use theAsyncResource JavaScript API so that all the appropriate callbacks are called.

Class:AsyncLocalStorage#

The documentation for this class has movedAsyncLocalStorage.