Request tracing
Attach correlation or request identifiers to asynchronous server work without threading them through every function parameter.
Node.js · Class
AsyncLocalStorage
AsyncLocalStorage maintains context-specific state across asynchronous callbacks and promise chains. Use run() or enterWith() to establish a store and getStore() to retrieve it.
- Since
- v12.17.0
How it works
AsyncLocalStorage provides per-instance state that follows asynchronous callbacks and promise chains. Create a context with run() or enterWith(), then retrieve the active store with getStore(); run() confines the store to its callback and asynchronous work created there.
Syntax
new AsyncLocalStorage([options]); asyncLocalStorage.disable(); asyncLocalStorage.getStore(); asyncLocalStorage.enterWith(store); asyncLocalStorage.run(store, callback[, ...args]);Parameters
| Name | Type | Description |
|---|---|---|
options | object | Optional configuration object accepted by the constructor in the current API. |
store | any | The value to make current for the context. |
callback | Function | The function executed inside the context. |
args | any[] | The value to supply to the callback. |
Returns
The constructor returns an AsyncLocalStorage instance; getStore() returns the active store or undefined; run() returns the callback's return value; enterWith() and disable() return undefined.
Key points
- Use the class to carry contextual state across asynchronous callbacks and promise-based workflows.
- A store remains consistent while execution crosses asynchronous boundaries.
- Separate instances isolate their stores, preventing accidental context sharing between unrelated concerns.
- Instantiate the class before defining the contexts your application will manage.
- getStore() reads the store associated with the currently active asynchronous context.
- enterWith() immediately makes a supplied store active for the rest of the current synchronous turn.
- run() establishes scoped context while preserving the callback's return value.
Common mistakes
- Calling getStore() without first establishing a context produces no active store.
- A store established with run() is scoped to that callback and work spawned from it, not surrounding code.
- After disable(), the instance remains unavailable until run() or enterWith() establishes context again.
Example: Propagate request context
import { AsyncLocalStorage } from 'node:async_hooks';
const requestContext = new AsyncLocalStorage<{ requestId: string }>();
function handleRequest(requestId: string) {
return requestContext.run({ requestId }, async () => {
await Promise.resolve();
return requestContext.getStore()?.requestId;
});
}
handleRequest('req-42').then(console.log);Creates a request context, preserves it across an asynchronous boundary, and reads the request ID from the active store.
When to use it
Contextual logging
Make request-scoped logging metadata available throughout callbacks and promise chains.
Scoped application state
Propagate transaction, authentication, or tenant state across asynchronous operations.
Interview questions
QWhat problem does AsyncLocalStorage solve?
AsyncLocalStorage associates a store with the current asynchronous execution context. The context propagates through callbacks and promise chains, allowing request-scoped data to be read without passing it through every function.
Follow-up: How do you initialize and read the context? Use run(store, callback) or enterWith(store), then call getStore() inside the callback or propagated asynchronous work.
QHow does run() differ from enterWith()?
run() executes a callback synchronously within a supplied context and returns the callback's result. The store is available to asynchronous operations created by that callback, but not to code outside its scope.
Follow-up: When would enterWith() be used? It changes the context for the rest of the current synchronous execution and carries it into subsequent asynchronous calls.
QWhat does getStore() return when no context is active?
Each AsyncLocalStorage instance has its own independent storage context, so separate instances can coexist without sharing data. getStore() returns the active store, or undefined when no initialized context is present.
Follow-up: How can an instance be reset? Call disable(); getStore() then returns undefined until run() or enterWith() is used again.
Related
AsyncResourceasync_hooksexecutionAsyncResourceexecutionAsyncId