Node.js async_hooks Module Guide

The async_hooks module provides an API to track asynchronous resources in Node.js. Here's how to use it for debugging, tracing, and context propagation.

Basic Setup#

import async_hooks from 'node:async_hooks';

// Create hook instance
const hook = async_hooks.createHook({
  init(asyncId, type, triggerAsyncId, resource) {
    console.log(`Init: ${type} (${asyncId}) triggered by ${triggerAsyncId}`);
  },
  before(asyncId) {
    console.log(`Before: ${asyncId}`);
  },
  after(asyncId) {
    console.log(`After: ${asyncId}`);
  },
  destroy(asyncId) {
    console.log(`Destroy: ${asyncId}`);
  },
});

// Enable the hook
hook.enable();

// Your async code here
setTimeout(() => {
  console.log('Timer fired');
}, 100);

// Disable when done
// hook.disable();

AsyncLocalStorage (Recommended)#

import { AsyncLocalStorage } from 'node:async_hooks';

// Create storage instance
const asyncLocalStorage = new AsyncLocalStorage();

// Run with context
function handleRequest(req, res) {
  const context = {
    requestId: crypto.randomUUID(),
    userId: req.user?.id,
    startTime: Date.now(),
  };

  asyncLocalStorage.run(context, () => {
    processRequest(req, res);
  });
}

// Access context anywhere in the call chain
function processRequest(req, res) {
  const context = asyncLocalStorage.getStore();
  console.log(`Processing request ${context.requestId}`);

  // Context is available in async callbacks too
  setTimeout(() => {
    const ctx = asyncLocalStorage.getStore();
    console.log(`Still have context: ${ctx.requestId}`);
  }, 100);
}

Request Tracing#

import { AsyncLocalStorage } from 'node:async_hooks';
import http from 'node:http';

const requestContext = new AsyncLocalStorage();

// Logger that includes request context
function log(message) {
  const ctx = requestContext.getStore();
  const prefix = ctx ? `[${ctx.requestId}]` : '[no-context]';
  console.log(`${prefix} ${message}`);
}

// Middleware to set up context
function contextMiddleware(req, res, next) {
  const context = {
    requestId: req.headers['x-request-id'] || crypto.randomUUID(),
    method: req.method,
    url: req.url,
    startTime: Date.now(),
  };

  requestContext.run(context, () => {
    res.on('finish', () => {
      const ctx = requestContext.getStore();
      const duration = Date.now() - ctx.startTime;
      log(`${ctx.method} ${ctx.url} completed in ${duration}ms`);
    });

    next();
  });
}

// Usage in route handlers
async function getUser(id) {
  log(`Fetching user ${id}`);
  // Context preserved through async operations
  const user = await database.findUser(id);
  log(`Found user: ${user.name}`);
  return user;
}

Execution Context Tracking#

import async_hooks from 'node:async_hooks';
import fs from 'node:fs';

// Track execution contexts
const contexts = new Map();
let currentId = -1;

const hook = async_hooks.createHook({
  init(asyncId, type, triggerAsyncId) {
    // Inherit context from trigger
    if (contexts.has(triggerAsyncId)) {
      contexts.set(asyncId, contexts.get(triggerAsyncId));
    }
  },
  before(asyncId) {
    currentId = asyncId;
  },
  after() {
    currentId = -1;
  },
  destroy(asyncId) {
    contexts.delete(asyncId);
  },
});

hook.enable();

function setContext(ctx) {
  const asyncId = async_hooks.executionAsyncId();
  contexts.set(asyncId, ctx);
}

function getContext() {
  const asyncId = async_hooks.executionAsyncId();
  return contexts.get(asyncId);
}

// Usage
setContext({ user: 'john', transaction: 'tx-123' });

setTimeout(() => {
  console.log(getContext()); // { user: 'john', transaction: 'tx-123' }
}, 100);

Performance Monitoring#

import { AsyncLocalStorage } from 'node:async_hooks';

const performanceContext = new AsyncLocalStorage();

class PerformanceTracker {
  constructor() {
    this.spans = [];
  }

  startSpan(name) {
    const span = {
      name,
      startTime: process.hrtime.bigint(),
      endTime: null,
      children: [],
    };
    this.spans.push(span);
    return span;
  }

  endSpan(span) {
    span.endTime = process.hrtime.bigint();
    span.duration = Number(span.endTime - span.startTime) / 1e6; // ms
  }

  getReport() {
    return this.spans.map((s) => ({
      name: s.name,
      duration: `${s.duration?.toFixed(2)}ms`,
    }));
  }
}

async function trackedOperation(name, fn) {
  const tracker = performanceContext.getStore();
  if (!tracker) return fn();

  const span = tracker.startSpan(name);
  try {
    return await fn();
  } finally {
    tracker.endSpan(span);
  }
}

// Usage
async function handleRequest(req) {
  const tracker = new PerformanceTracker();

  return performanceContext.run(tracker, async () => {
    await trackedOperation('validateRequest', () => validate(req));
    await trackedOperation('fetchData', () => fetchFromDB());
    await trackedOperation('processData', () => process());

    console.log(tracker.getReport());
  });
}

Database Transaction Context#

import { AsyncLocalStorage } from 'node:async_hooks';

const transactionContext = new AsyncLocalStorage();

class TransactionManager {
  async runInTransaction(fn) {
    const connection = await pool.getConnection();
    await connection.beginTransaction();

    try {
      const result = await transactionContext.run(connection, fn);
      await connection.commit();
      return result;
    } catch (error) {
      await connection.rollback();
      throw error;
    } finally {
      connection.release();
    }
  }
}

// Repository that uses transaction context
class UserRepository {
  async create(userData) {
    const conn = transactionContext.getStore() || pool;
    return conn.query('INSERT INTO users SET ?', userData);
  }

  async update(id, data) {
    const conn = transactionContext.getStore() || pool;
    return conn.query('UPDATE users SET ? WHERE id = ?', [data, id]);
  }
}

// Usage
const txManager = new TransactionManager();
const userRepo = new UserRepository();

await txManager.runInTransaction(async () => {
  await userRepo.create({ name: 'John' });
  await userRepo.update(1, { status: 'active' });
  // Both operations use same transaction
});

Error Context Propagation#

import { AsyncLocalStorage } from 'node:async_hooks';

const errorContext = new AsyncLocalStorage();

class ContextualError extends Error {
  constructor(message) {
    super(message);
    this.context = errorContext.getStore() || {};
  }
}

function withErrorContext(context, fn) {
  const current = errorContext.getStore() || {};
  return errorContext.run({ ...current, ...context }, fn);
}

// Usage
async function processOrder(orderId) {
  return withErrorContext({ orderId }, async () => {
    const order = await fetchOrder(orderId);

    return withErrorContext({ customerId: order.customerId }, async () => {
      // If error occurs here, it includes orderId and customerId
      await processPayment(order);
    });
  });
}

// Error handler
process.on('uncaughtException', (error) => {
  if (error instanceof ContextualError) {
    console.error('Error with context:', {
      message: error.message,
      context: error.context,
      stack: error.stack,
    });
  }
});

Resource Cleanup Tracking#

import async_hooks from 'node:async_hooks';

const activeResources = new Map();

const hook = async_hooks.createHook({
  init(asyncId, type, triggerAsyncId, resource) {
    activeResources.set(asyncId, {
      type,
      triggerAsyncId,
      createdAt: Date.now(),
      stack: new Error().stack,
    });
  },
  destroy(asyncId) {
    activeResources.delete(asyncId);
  },
});

hook.enable();

// Check for leaks periodically
setInterval(() => {
  const now = Date.now();
  const leaks = [];

  for (const [id, info] of activeResources) {
    const age = now - info.createdAt;
    if (age > 30000) {
      // 30 seconds
      leaks.push({
        asyncId: id,
        type: info.type,
        age: `${(age / 1000).toFixed(1)}s`,
      });
    }
  }

  if (leaks.length > 0) {
    console.warn('Potential resource leaks:', leaks);
  }
}, 10000);

Logging Context#

import { AsyncLocalStorage } from 'node:async_hooks';

const logContext = new AsyncLocalStorage();

class Logger {
  static log(level, message, meta = {}) {
    const ctx = logContext.getStore() || {};
    const logEntry = {
      timestamp: new Date().toISOString(),
      level,
      message,
      ...ctx,
      ...meta,
    };
    console.log(JSON.stringify(logEntry));
  }

  static info(message, meta) {
    this.log('info', message, meta);
  }

  static error(message, meta) {
    this.log('error', message, meta);
  }

  static withContext(context, fn) {
    const current = logContext.getStore() || {};
    return logContext.run({ ...current, ...context }, fn);
  }
}

// Usage
async function handleRequest(req) {
  return Logger.withContext(
    { requestId: req.id, userId: req.user?.id },
    async () => {
      Logger.info('Request started');

      await Logger.withContext({ operation: 'fetchUser' }, async () => {
        Logger.info('Fetching user data');
        // Logs include requestId, userId, and operation
      });

      Logger.info('Request completed');
    }
  );
}

Best Practices#

AsyncLocalStorage:
✓ Prefer over raw async_hooks
✓ Use for request context
✓ Use for transaction scoping
✓ Use for logging context

Performance:
✓ Minimize hook callbacks
✓ Avoid heavy processing in hooks
✓ Disable when not needed
✓ Use sampling for tracing

Patterns:
✓ Request ID propagation
✓ Transaction management
✓ Performance tracing
✓ Error context enrichment

Avoid:
✗ Storing large objects in context
✗ Modifying context after creation
✗ Relying on context in cleanup
✗ Circular references in context

The async_hooks module enables powerful async context tracking in Node.js. Use AsyncLocalStorage for request tracing, transaction management, and contextual logging. It automatically propagates context through async boundaries without manual passing. For advanced use cases like resource tracking and debugging, use the lower-level createHook API. Remember that async_hooks has performance overhead, so use it judiciously in production.