Node.js Async Hooks Module Guide

The async_hooks module tracks the lifecycle of asynchronous resources. Here's how to use it.

Basic Usage#

const async_hooks = require('async_hooks');
const fs = require('fs');

// Create hook instance
const hook = async_hooks.createHook({
  init(asyncId, type, triggerAsyncId, resource) {
    // Called when async resource is created
    fs.writeSync(
      1,
      `Init: ${type}(${asyncId}) trigger: ${triggerAsyncId}\n`
    );
  },

  before(asyncId) {
    // Called before async callback runs
    fs.writeSync(1, `Before: ${asyncId}\n`);
  },

  after(asyncId) {
    // Called after async callback completes
    fs.writeSync(1, `After: ${asyncId}\n`);
  },

  destroy(asyncId) {
    // Called when async resource is destroyed
    fs.writeSync(1, `Destroy: ${asyncId}\n`);
  },
});

// Enable the hook
hook.enable();

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

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

Execution Context Tracking#

const async_hooks = require('async_hooks');

// Track async context
const contexts = new Map();

const hook = async_hooks.createHook({
  init(asyncId, type, triggerAsyncId) {
    // Inherit context from trigger
    if (contexts.has(triggerAsyncId)) {
      contexts.set(asyncId, contexts.get(triggerAsyncId));
    }
  },

  destroy(asyncId) {
    contexts.delete(asyncId);
  },
});

hook.enable();

// Set context for current execution
function setContext(data) {
  const asyncId = async_hooks.executionAsyncId();
  contexts.set(asyncId, data);
}

// Get context for current execution
function getContext() {
  const asyncId = async_hooks.executionAsyncId();
  return contexts.get(asyncId);
}

// Usage
async function handleRequest(requestId) {
  setContext({ requestId });

  await someAsyncOperation();

  const ctx = getContext();
  console.log('Request:', ctx.requestId); // Still has context
}

AsyncLocalStorage#

const { AsyncLocalStorage } = require('async_hooks');

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

// Middleware pattern
function requestMiddleware(req, res, next) {
  const context = {
    requestId: generateId(),
    startTime: Date.now(),
    userId: req.userId,
  };

  requestContext.run(context, () => {
    next();
  });
}

// Access context anywhere in async chain
function logMessage(message) {
  const ctx = requestContext.getStore();
  console.log(`[${ctx?.requestId}] ${message}`);
}

// Service function
async function getUserData(userId) {
  const ctx = requestContext.getStore();
  logMessage(`Fetching user ${userId}`);

  const data = await db.findUser(userId);

  logMessage(`Found user: ${data.name}`);
  return data;
}

// Usage
app.use(requestMiddleware);

app.get('/user/:id', async (req, res) => {
  const user = await getUserData(req.params.id);
  res.json(user);
});

Request Tracing#

const { AsyncLocalStorage } = require('async_hooks');
const crypto = require('crypto');

class RequestTracer {
  constructor() {
    this.storage = new AsyncLocalStorage();
  }

  startTrace(parentTraceId = null) {
    const trace = {
      traceId: parentTraceId || crypto.randomUUID(),
      spanId: crypto.randomUUID(),
      parentSpanId: parentTraceId ? crypto.randomUUID() : null,
      startTime: process.hrtime.bigint(),
      spans: [],
    };

    return trace;
  }

  run(fn) {
    const trace = this.startTrace();
    return this.storage.run(trace, fn);
  }

  getTrace() {
    return this.storage.getStore();
  }

  addSpan(name, fn) {
    const trace = this.getTrace();
    const span = {
      name,
      spanId: crypto.randomUUID(),
      startTime: process.hrtime.bigint(),
    };

    trace?.spans.push(span);

    const result = fn();

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

    return result;
  }

  getHeaders() {
    const trace = this.getTrace();
    return {
      'x-trace-id': trace?.traceId,
      'x-span-id': trace?.spanId,
    };
  }
}

const tracer = new RequestTracer();

// Usage
app.use((req, res, next) => {
  tracer.run(() => next());
});

async function processOrder(orderId) {
  return tracer.addSpan('processOrder', async () => {
    await tracer.addSpan('validateOrder', () => validate(orderId));
    await tracer.addSpan('chargePayment', () => charge(orderId));
    await tracer.addSpan('sendConfirmation', () => notify(orderId));
  });
}

Logger with Context#

const { AsyncLocalStorage } = require('async_hooks');

class ContextLogger {
  constructor() {
    this.storage = new AsyncLocalStorage();
  }

  withContext(context, fn) {
    return this.storage.run(context, fn);
  }

  addContext(additionalContext) {
    const current = this.storage.getStore() || {};
    return { ...current, ...additionalContext };
  }

  log(level, message, data = {}) {
    const context = this.storage.getStore() || {};
    const logEntry = {
      timestamp: new Date().toISOString(),
      level,
      message,
      ...context,
      ...data,
    };

    console.log(JSON.stringify(logEntry));
  }

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

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

  warn(message, data) {
    this.log('warn', message, data);
  }
}

const logger = new ContextLogger();

// Usage
app.use((req, res, next) => {
  const context = {
    requestId: req.headers['x-request-id'] || generateId(),
    path: req.path,
    method: req.method,
  };

  logger.withContext(context, () => {
    logger.info('Request started');
    next();
  });
});

// Anywhere in code
async function processData(data) {
  logger.info('Processing data', { dataSize: data.length });

  try {
    const result = await transform(data);
    logger.info('Processing complete', { resultSize: result.length });
    return result;
  } catch (error) {
    logger.error('Processing failed', { error: error.message });
    throw error;
  }
}

Database Connection Tracking#

const { AsyncLocalStorage } = require('async_hooks');

class TransactionManager {
  constructor() {
    this.storage = new AsyncLocalStorage();
  }

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

    try {
      await connection.beginTransaction();

      const result = await this.storage.run({ connection }, fn);

      await connection.commit();
      return result;
    } catch (error) {
      await connection.rollback();
      throw error;
    } finally {
      connection.release();
    }
  }

  getConnection() {
    const store = this.storage.getStore();
    return store?.connection;
  }
}

const txManager = new TransactionManager();

// Repository
class UserRepository {
  async create(userData) {
    const conn = txManager.getConnection();
    if (conn) {
      // Use transaction connection
      return conn.query('INSERT INTO users SET ?', userData);
    }
    // Use pool directly
    return pool.query('INSERT INTO users SET ?', userData);
  }

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

// Usage
await txManager.runInTransaction(async () => {
  const user = await userRepo.create({ name: 'Alice' });
  await orderRepo.create({ userId: user.id, amount: 100 });
  // Both use same connection, auto-rollback on error
});

Performance Monitoring#

const async_hooks = require('async_hooks');

class AsyncMonitor {
  constructor() {
    this.resources = new Map();
    this.stats = {
      created: 0,
      destroyed: 0,
      active: 0,
      byType: {},
    };

    this.hook = async_hooks.createHook({
      init: this.onInit.bind(this),
      destroy: this.onDestroy.bind(this),
    });
  }

  onInit(asyncId, type, triggerAsyncId) {
    this.resources.set(asyncId, {
      type,
      triggerAsyncId,
      createdAt: Date.now(),
    });

    this.stats.created++;
    this.stats.active++;
    this.stats.byType[type] = (this.stats.byType[type] || 0) + 1;
  }

  onDestroy(asyncId) {
    const resource = this.resources.get(asyncId);
    if (resource) {
      this.stats.destroyed++;
      this.stats.active--;
      this.stats.byType[resource.type]--;
      this.resources.delete(asyncId);
    }
  }

  enable() {
    this.hook.enable();
  }

  disable() {
    this.hook.disable();
  }

  getStats() {
    return {
      ...this.stats,
      pending: this.stats.active,
    };
  }

  getActiveResources() {
    return Array.from(this.resources.entries()).map(([id, resource]) => ({
      asyncId: id,
      ...resource,
      age: Date.now() - resource.createdAt,
    }));
  }
}

const monitor = new AsyncMonitor();
monitor.enable();

// Check stats periodically
setInterval(() => {
  console.log('Async stats:', monitor.getStats());
}, 5000);

Error Tracking#

const { AsyncLocalStorage } = require('async_hooks');

class ErrorTracker {
  constructor() {
    this.storage = new AsyncLocalStorage();
  }

  withErrorContext(context, fn) {
    return this.storage.run(
      {
        ...context,
        breadcrumbs: [],
      },
      fn
    );
  }

  addBreadcrumb(message, data = {}) {
    const store = this.storage.getStore();
    if (store) {
      store.breadcrumbs.push({
        timestamp: Date.now(),
        message,
        data,
      });
    }
  }

  captureException(error) {
    const store = this.storage.getStore() || {};
    return {
      error: {
        name: error.name,
        message: error.message,
        stack: error.stack,
      },
      context: {
        requestId: store.requestId,
        userId: store.userId,
        path: store.path,
      },
      breadcrumbs: store.breadcrumbs || [],
    };
  }
}

const errorTracker = new ErrorTracker();

// Middleware
app.use((req, res, next) => {
  errorTracker.withErrorContext(
    {
      requestId: generateId(),
      userId: req.userId,
      path: req.path,
    },
    () => next()
  );
});

// Add breadcrumbs
async function checkout(cart) {
  errorTracker.addBreadcrumb('Starting checkout', { items: cart.length });

  const total = calculateTotal(cart);
  errorTracker.addBreadcrumb('Calculated total', { total });

  try {
    const result = await processPayment(total);
    errorTracker.addBreadcrumb('Payment processed');
    return result;
  } catch (error) {
    const report = errorTracker.captureException(error);
    sendToErrorService(report);
    throw error;
  }
}

Best Practices#

Usage:
✓ Prefer AsyncLocalStorage over raw hooks
✓ Use for request context propagation
✓ Use for transaction management
✓ Use for distributed tracing

Performance:
✓ Minimize work in hook callbacks
✓ Use writeSync for debugging
✓ Clean up resources in destroy
✓ Disable hooks when not needed

Patterns:
✓ Logger with request context
✓ Transaction scoping
✓ Error tracking with breadcrumbs
✓ Performance monitoring

Avoid:
✗ Storing large objects
✗ Synchronous operations in hooks
✗ Memory leaks from missing cleanup
✗ Using for simple use cases

The async_hooks module enables tracking asynchronous operations in Node.js. Use AsyncLocalStorage for request context propagation, logging correlation, and transaction management. Raw async hooks are useful for debugging, profiling, and building custom instrumentation. Always clean up resources properly to prevent memory leaks.