Async hooks

Ajouté en: v8.1.0

Code source: lib/async_hooks.js

The node:async_hooks module provides an API to track asynchronous resources. It can be accessed using:

MJScopy

CJScopy

Terminology

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

If Workers are used, each thread has an independent async_hooks interface, and each thread will use a new set of async IDs.

Overview

Following is a simple overview of the public API.

MJScopy

CJScopy

M async_hooks.createHook(callbacks)

Ajouté en: v8.1.0

• callbacks Object The Hook Callbacks to register
  • init Function The init callback.
  • before Function The before callback.
  • after Function The after callback.
  • destroy Function The destroy callback.
  • promiseResolve Function The promiseResolve callback.
• Returns: AsyncHook Instance used for disabling and enabling hooks

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

The callbacks init()/before()/after()/destroy() are called for the respective asynchronous event during a resource's lifetime.

All callbacks are optional. For example, if only resource cleanup needs to be tracked, then only the destroy callback needs to be passed. The specifics of all functions that can be passed to callbacks is in the Hook Callbacks section.

MJScopy

CJScopy

The callbacks will be inherited via the prototype chain:

JScopy

Because promises are asynchronous resources whose lifecycle is tracked via the async hooks mechanism, the init(), before(), after(), and destroy() callbacks must not be async functions that return promises.

Error handling

If any AsyncHook callbacks throw, the application will print the stack trace and exit. The exit path does follow that of an uncaught exception, but all 'uncaughtException' listeners are removed, thus forcing the process to exit. The 'exit' callbacks will still be called unless the application is run with --abort-on-uncaught-exception, in which case a stack trace will be printed and the application exits, leaving a core file.

The reason for this error handling behavior is that these callbacks are running at potentially volatile points in an object's lifetime, for example during class construction and destruction. Because of this, it is deemed necessary to bring down the process quickly in order to prevent an unintentional abort in the future. This is subject to change in the future if a comprehensive analysis is performed to ensure an exception can follow the normal control flow without unintentional side effects.

Printing in AsyncHook callbacks

Because printing to the console is an asynchronous operation, console.log() will cause AsyncHook callbacks to be called. Using console.log() or similar asynchronous operations inside an AsyncHook callback function will cause an infinite recursion. An easy solution to this when debugging is to use a synchronous logging operation such as fs.writeFileSync(file, msg, flag). This will print to the file and will not invoke AsyncHook recursively because it is synchronous.

MJScopy

CJScopy

If an asynchronous operation is needed for logging, it is possible to keep track of what caused the asynchronous operation using the information provided by AsyncHook itself. The logging should then be skipped when it was the logging itself that caused the AsyncHook callback to be called. By doing this, the otherwise infinite recursion is broken.

C AsyncHook

The class AsyncHook exposes an interface for tracking lifetime events of asynchronous operations.

M asyncHook.enable()

• Returns: AsyncHook A reference to asyncHook.

Enable the callbacks for a given AsyncHook instance. If no callbacks are provided, enabling is a no-op.

The AsyncHook instance is disabled by default. If the AsyncHook instance should be enabled immediately after creation, the following pattern can be used.

MJScopy

CJScopy

M asyncHook.disable()

• Returns: AsyncHook A reference to asyncHook.

Disable the callbacks for a given AsyncHook instance from the global pool of AsyncHook callbacks to be executed. Once a hook has been disabled it will not be called again until enabled.

For API consistency disable() also returns the AsyncHook instance.

Hook callbacks

Key events in the lifetime of asynchronous events have been categorized into four areas: instantiation, before/after the callback is called, and when the instance is destroyed.

M init(asyncId, type, triggerAsyncId, resource)

• asyncId number A unique ID for the async resource.
• type string The type of the async resource.
• triggerAsyncId number The unique ID of the async resource in whose execution context this async resource was created.
• resource Object Reference to the resource representing the async operation, needs to be released during destroy.

Called when a class is constructed that has the possibility to emit an asynchronous event. This does not mean the instance must call before/after before destroy is called, only that the possibility exists.

This behavior can be observed by doing something like opening a resource then closing it before the resource can be used. The following snippet demonstrates this.

MJScopy

CJScopy

Every new resource is assigned an ID that is unique within the scope of the current Node.js instance.

type

The type is a string identifying the type of resource that caused init to be called. Generally, it will correspond to the name of the resource's constructor.

Valid values are:

TEXTcopy

These values can change in any Node.js release. Furthermore users of AsyncResource likely provide other values.

There is also the PROMISE resource type, which is used to track Promise instances and asynchronous work scheduled by them.

Users are able to define their own type when using the public embedder API.

It is possible to have type name collisions. Embedders are encouraged to use unique prefixes, such as the npm package name, to prevent collisions when listening to the hooks.

triggerAsyncId

triggerAsyncId is the asyncId of the resource that caused (or "triggered") the new resource to initialize and that caused init to call. This is different from async_hooks.executionAsyncId() that only shows when a resource was created, while triggerAsyncId shows why a resource was created.

The following is a simple demonstration of triggerAsyncId:

MJScopy

CJScopy

Output when hitting the server with nc localhost 8080:

BASHcopy

The TCPSERVERWRAP is the server which receives the connections.

The TCPWRAP is the new connection from the client. When a new connection is made, the TCPWrap instance is immediately constructed. This happens outside of any JavaScript stack. (An executionAsyncId() of 0 means that it is being executed from C++ with no JavaScript stack above it.) With only that information, it would be impossible to link resources together in terms of what caused them to be created, so triggerAsyncId is given the task of propagating what resource is responsible for the new resource's existence.

resource

resource is an object that represents the actual async resource that has been initialized. This can contain useful information that can vary based on the value of type. For instance, for the GETADDRINFOREQWRAP resource type, resource provides the host name used when looking up the IP address for the host in net.Server.listen(). The API for accessing this information is not supported, but using the Embedder API, users can provide and document their own resource objects. For example, such a resource object could contain the SQL query being executed.

In some cases the resource object is reused for performance reasons, it is thus not safe to use it as a key in a WeakMap or add properties to it.

Asynchronous context example

The following is an example with additional information about the calls to init between the before and after calls, specifically what the callback to listen() will look like. The output formatting is slightly more elaborate to make calling context easier to see.

JScopy

Output from only starting the server:

BASHcopy

As illustrated in the example, executionAsyncId() and execution each specify the value of the current execution context; which is delineated by calls to before and after.

Only using execution to graph resource allocation results in the following:

BASHcopy

The TCPSERVERWRAP is not part of this graph, even though it was the reason for console.log() being called. This is because binding to a port without a host name is a synchronous operation, but to maintain a completely asynchronous API the user's callback is placed in a process.nextTick(). Which is why TickObject is present in the output and is a 'parent' for .listen() callback.

The graph only shows when a resource was created, not why, so to track the why use triggerAsyncId. Which can be represented with the following graph:

BASHcopy

M before(asyncId)

• asyncId number

When an asynchronous operation is initiated (such as a TCP server receiving a new connection) or completes (such as writing data to disk) a callback is called to notify the user. The before callback is called just before said callback is executed. asyncId is the unique identifier assigned to the resource about to execute the callback.

The before callback will be called 0 to N times. The before callback will typically be called 0 times if the asynchronous operation was cancelled or, for example, if no connections are received by a TCP server. Persistent asynchronous resources like a TCP server will typically call the before callback multiple times, while other operations like fs.open() will call it only once.

M after(asyncId)

• asyncId number

Called immediately after the callback specified in before is completed.

If an uncaught exception occurs during execution of the callback, then after will run after the 'uncaughtException' event is emitted or a domain's handler runs.

M destroy(asyncId)

• asyncId number

Called after the resource corresponding to asyncId is destroyed. It is also called asynchronously from the embedder API emitDestroy().

Some resources depend on garbage collection for cleanup, so if a reference is made to the resource object passed to init it is possible that destroy will never be called, causing a memory leak in the application. If the resource does not depend on garbage collection, then this will not be an issue.

M promiseResolve(asyncId)

Ajouté en: v8.6.0

• asyncId number

Called when the resolve function passed to the Promise constructor is invoked (either directly or through other means of resolving a promise).

resolve() does not do any observable synchronous work.

The Promise is not necessarily fulfilled or rejected at this point if the Promise was resolved by assuming the state of another Promise.

JScopy

calls the following callbacks:

TEXTcopy

M async_hooks.executionAsyncResource()

Ajouté en: v13.9.0, v12.17.0

• Returns: Object The resource representing the current execution. Useful to store data within the resource.

Resource objects returned by executionAsyncResource() are most often internal Node.js handle objects with undocumented APIs. Using any functions or properties on the object is likely to crash your application and should be avoided.

Using executionAsyncResource() in the top-level execution context will return an empty object as there is no handle or request object to use, but having an object representing the top-level can be helpful.

MJScopy

CJScopy

This can be used to implement continuation local storage without the use of a tracking Map to store the metadata:

MJScopy

CJScopy

M async_hooks.executionAsyncId()

• Returns: number The asyncId of the current execution context. Useful to track when something calls.

MJScopy

CJScopy

The ID returned from executionAsyncId() is related to execution timing, not causality (which is covered by triggerAsyncId()):

JScopy

Promise contexts may not get precise executionAsyncIds by default. See the section on promise execution tracking.

M async_hooks.triggerAsyncId()

• Returns: number The ID of the resource responsible for calling the callback that is currently being executed.

JScopy

Promise contexts may not get valid triggerAsyncIds by default. See the section on promise execution tracking.

M async_hooks.asyncWrapProviders

Ajouté en: v16.14.0

• Returns: A map of provider types to the corresponding numeric id. This map contains all the event types that might be emitted by the async_hooks.init() event.

This feature suppresses the deprecated usage of process.binding('async_wrap').Providers. See: DEP0111

Promise execution tracking

By default, promise executions are not assigned asyncIds due to the relatively expensive nature of the promise introspection API provided by V8. This means that programs using promises or async/await will not get correct execution and trigger ids for promise callback contexts by default.

MJScopy

CJScopy

Observe that the then() callback claims to have executed in the context of the outer scope even though there was an asynchronous hop involved. Also, the triggerAsyncId value is 0, which means that we are missing context about the resource that caused (triggered) the then() callback to be executed.

Installing async hooks via async_hooks.createHook enables promise execution tracking:

MJScopy

CJScopy

In this example, adding any actual hook function enabled the tracking of promises. There are two promises in the example above; the promise created by Promise.resolve() and the promise returned by the call to then(). In the example above, the first promise got the asyncId 6 and the latter got asyncId 7. During the execution of the then() callback, we are executing in the context of promise with asyncId 7. This promise was triggered by async resource 6.

Another subtlety with promises is that before and after callbacks are run only on chained promises. That means promises not created by then()/catch() will not have the before and after callbacks fired on them. For more details see the details of the V8 PromiseHooks API.

JavaScript embedder API

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

C AsyncResource

The documentation for this class has moved AsyncResource.

C AsyncLocalStorage

The documentation for this class has moved AsyncLocalStorage.