Node.js AsyncLocalStorage: End-to-End Request Context Without the Propagation Hell

You need to trace a single request through your Node.js service. Today that means passing a context object — requestId, userId, maybe a pre-bound logger — through every function signature. handleRequest calls validateToken, which calls fetchUser, which calls logActivity. Somewhere around the fifth layer you forget to forward the requestId and your logs become a useless wall of unrelated noise. Or worse, you decide not to add a new parameter because refactoring twelve call sites is not worth it, and you ship broken observability instead.

AsyncLocalStorage fixes this. It is a Node.js core module that stores per-request state inside the async call chain, so any function running as part of that request can read the context without receiving it as an argument. No parameter drilling. No global singletons that break under concurrency. No broken traces.

This post is the practical setup: a five-line Express middleware, a logger that enriches itself, database query tagging, and the three production pitfalls that cost you context when you least expect it.

What AsyncLocalStorage actually does

Introduced in Node.js v16.4 and stabilized shortly after, AsyncLocalStorage is built on top of async_hooks. It creates a key-value store scoped to an asynchronous execution context — essentially a request, a background job, or any AsyncResource. Values set inside that context are visible to every callback, Promise resolution, and async function that runs within it.

The mental model is simple: when a request arrives, you run() a function with a store. Everything that executes as a consequence of that function — including awaited Promises, event handlers, and setImmediate callbacks — shares the same store. When the async chain ends, the store is garbage-collected along with it.

The performance cost is negligible on Node.js 18+. The Node.js team optimized it to a single pointer write per async boundary. Microseconds per request, not milliseconds.

The setup: Express middleware in five lines

Here is the smallest useful setup. An Express middleware enters a new AsyncLocalStorage context for every request. Downstream middleware, route handlers, and any function they call can read the context without ever receiving it.

// context.js
import { AsyncLocalStorage } from 'node:async_hooks';

export const asyncLocalStorage = new AsyncLocalStorage();

export function getRequestContext() {
  return asyncLocalStorage.getStore();
}

// app.js
import express from 'express';
import crypto from 'node:crypto';
import { asyncLocalStorage } from './context.js';

const app = express();

app.use((req, res, next) => {
  const store = new Map();
  store.set('requestId', req.get('x-request-id') ?? crypto.randomUUID());
  store.set('startTime', performance.now());
  store.set('userId', null); // populated later by auth middleware

  asyncLocalStorage.run(store, () => {
    next();
  });
});

That is the entire plumbing. next() runs inside the AsyncLocalStorage context, so everything downstream — route handlers, database queries, error handlers — can call getRequestContext() and read the requestId. The Map is created per request, so concurrent requests do not collide.

A logger that just knows

The most immediate payoff is structured logging. Instead of passing a pre-bound logger into every utility function, you read the context at log time:

// logger.js
import { getRequestContext } from './context.js';

function log(level, message, meta = {}) {
  const ctx = getRequestContext();
  const enriched = {
    ...(ctx
      ? { requestId: ctx.get('requestId'), userId: ctx.get('userId') }
      : {}),
    ...meta,
  };
  console.log(
    JSON.stringify({
      level,
      message,
      ...enriched,
      time: new Date().toISOString(),
    })
  );
}

export const logger = {
  info: (message, meta) => log('info', message, meta),
  error: (message, err, meta) => log('error', message, { error: err.message, stack: err.stack, ...meta }),
};

// users.js
import { logger } from './logger.js';

export async function fetchUser(userId) {
  logger.info('fetching user', { userId });
  // requestId and userId are present automatically
}

Before AsyncLocalStorage, you had three bad choices:

Pass logger everywhere — clutters signatures and couples every utility to your logging abstraction.
Use a global singleton — breaks under concurrency because requests interleave in the same process.
Use the old continuation-local-storage npm package — worked, but was slower and had edge cases with native Promises.

AsyncLocalStorage is the first built-in solution that is fast enough and correct enough for production logging.

Tagging database queries with the request ID

A more advanced use: annotating every database query so Postgres pg_stat_statements or slow-query logs show which HTTP request triggered it.

// db.js
import pg from 'pg';
import { getRequestContext } from './context.js';

const pool = new pg.Pool({ /* connection config */ });

export async function query(sql, params) {
  const ctx = getRequestContext();
  const requestId = ctx?.get('requestId');

  // Postgres ignores SQL comments in planning and execution, but logs them.
  const taggedSql = requestId
    ? `/* requestId=${requestId} */ ${sql}`
    : sql;

  return pool.query(taggedSql, params);
}

Now when you see a slow query in pg_stat_statements, the embedded comment tells you the originating request. You do not need application-side query logging that duplicates what the database already records. This is especially useful in microservices where a single connection pool serves multiple concurrent requests.

Propagating context through auth middleware

The store is mutable. You can update it after creation as long as the mutation happens inside the same async chain.

// auth.js
import { asyncLocalStorage } from './context.js';

export async function authenticate(req, res, next) {
  const token = req.get('authorization')?.replace('Bearer ', '');
  const user = await verifyToken(token);

  const store = asyncLocalStorage.getStore();
  store.set('userId', user.id);
  store.set('roles', user.roles);

  next();
}

Because verifyToken and next() run inside the same AsyncLocalStorage context, getStore() returns the same Map. Any function called after next() sees the updated userId. Your logger switches from userId: null to userId: 42 without a single signature change.

Pitfall 1: Callbacks that escape the async chain

AsyncLocalStorage tracks asynchronous boundaries. If a callback escapes into a different scheduling queue without being properly awaited or wrapped, it can lose the context.

The common mistake is mixing callbacks with Promises inside Promise.all:

// DANGER: do not do this
await Promise.all(items.map(item => {
  setImmediate(() => processItem(item));
  // processItem loses ALS context because setImmediate
  // schedules outside the current async boundary.
}));

setImmediate schedules a new callback. Unless it is awaited or wrapped in a Promise, it may run in a different async context. The fix is to keep everything inside the Promise chain:

// SAFE: stays inside ALS
await Promise.all(items.map(async item => {
  await processItem(item);
}));

If you genuinely need deferred execution, wrap it explicitly:

await Promise.all(items.map(item => new Promise((resolve) => {
  setImmediate(() => resolve(processItem(item)));
})));

Pitfall 2: Worker threads and cluster mode

AsyncLocalStorage is bound to a single thread. If you dispatch work to a Worker via worker_threads, the worker runs in a different V8 isolate with its own async resource stack. The store does not transfer automatically.

If you need context in a worker, pass it explicitly in the message payload:

// main.js
import { Worker } from 'node:worker_threads';
import { getRequestContext } from './context.js';

const worker = new Worker('./worker.js');
const ctx = getRequestContext();

worker.postMessage({
  requestId: ctx.get('requestId'),
  payload: data,
});

// worker.js
import { parentPort } from 'node:worker_threads';

parentPort.on('message', ({ requestId, payload }) => {
  // re-hydrate context locally, or use the explicit fields
});

The same applies to cluster module child processes: there is no implicit propagation across process boundaries. Pass what you need.

Pitfall 3: Event emitters inside long-lived streams

If you attach an event handler to a stream or emitter that outlives the request, the handler retains the ALS context of the request that registered it. This is rarely what you want.

// DANGER
const emitter = getGlobalEventBus();
emitter.on('order.completed', (order) => {
  // This handler runs inside the ALS context of the *request that registered it*,
  // not the request that is active when the event fires.
  logger.info('order completed', { orderId: order.id });
});

For events that fire later, remove the listener when the request ends, or read the store only inside short-lived handlers. If the event is global, pass the needed fields in the event payload instead of relying on ambient context.

Combining with OpenTelemetry

If you already have distributed tracing set up, AsyncLocalStorage interoperates cleanly. OpenTelemetry stores the active span in an internal mechanism very similar to ALS. You can bridge the two by copying the traceId into your own store, so every log line contains both your requestId and the OTel trace ID.

// context.js
import { trace } from '@opentelemetry/api';
import { asyncLocalStorage } from './context.js';

export function getRequestContext() {
  const store = asyncLocalStorage.getStore();
  const span = trace.getActiveSpan();
  if (span && store && !store.has('traceId')) {
    store.set('traceId', span.spanContext().traceId);
  }
  return store;
}

Now your logs and your traces share a pivot key. During an incident, you grep a requestId in logs, copy the traceId, and jump straight to the full distributed trace without stitching timestamps by hand.

When not to use it

AsyncLocalStorage is not magic. Do not use it:

To replace explicit function arguments for domain logic. A userId that is central to a business calculation should still be a parameter. ALS is for cross-cutting concerns — tracing, logging, deadlines, security context.
As a general mutable cache. It is per-async-context, not a thread-local hash table for global state.
Inside CPU-bound tight loops with no async boundaries. If there is no await, there is no context boundary to track, and getStore() adds no value.

The practical pattern

For a typical Express or Fastify service, the pattern is:

Create one AsyncLocalStorage instance at module level.
In a middleware, run() with a Map and call next().
Any cross-cutting utility reads from getStore().
Mutate the store only in middleware that runs synchronously before the handler.
Do not pass the store into workers or long-lived event listeners without explicit re-hydration.

The result: your service gains request-scoped logging, query tagging, and deadline tracking without touching a single business-logic signature. The next time you need to add a new observability dimension — a tenantId, a featureFlag, a deadline — you add it in one middleware and one Map key. Every log line and database query picks it up automatically.

A note from Yojji

Keeping request context intact through deep call stacks, database drivers, and logging utilities — without cluttering every function signature — is exactly the kind of infrastructure refinement that separates a working prototype from a maintainable production service.

Yojji is an international custom software development company with teams across Europe, the US, and the UK, building production systems in the JavaScript ecosystem. Their engineers routinely work through these kinds of Node.js runtime details — request lifecycle, observability wiring, and async boundary behavior — to keep backend services predictable under real traffic.