Node.js Async Hooks: The Tracing API That Powers Every APM Tool

// Without async_hooks: context must be threaded through every call
app.get('/users', async (req, res) => {
 const requestId = req.headers['x-request-id'];
 const users = await getUsers(requestId); // Must pass requestId
 const enriched = await enrich(users, requestId); // Must pass requestId
 res.json(enriched);
});

async function getUsers(requestId) { // Must accept and thread requestId
 logger.info('Fetching users', { requestId }); // Tedious
 return db.query('SELECT * FROM users');
}

// With AsyncLocalStorage: context available anywhere, automatically
const store = new AsyncLocalStorage();

app.get('/users', async (req, res) => {
 await store.run({ requestId: req.headers['x-request-id'] }, async () => {
 const users = await getUsers(); // No context passing!
 res.json(users);
 });
});

async function getUsers() {
 const { requestId } = store.getStore(); // Context available here
 logger.info('Fetching users', { requestId }); // Zero plumbing
 return db.query('SELECT * FROM users');
}

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

const requestContext = new AsyncLocalStorage();

// Middleware: attach context to every request
app.use((req, res, next) => {
 const ctx = {
 requestId: req.headers['x-request-id'] || randomUUID(),
 userId: req.user?.id,
 startTime: Date.now(),
 spans: [],
 };
 res.setHeader('x-request-id', ctx.requestId);
 requestContext.run(ctx, next); // Everything in this request gets ctx
});

// Logger that automatically includes request context
const logger = {
 info: (msg, extra = {}) => {
 const ctx = requestContext.getStore() || {};
 console.log(JSON.stringify({
 level: 'info', msg, requestId: ctx.requestId,
 userId: ctx.userId, ...extra
 }));
 }
};

// Database wrapper that auto-traces queries
async function query(sql, params) {
 const ctx = requestContext.getStore();
 const start = Date.now();
 try {
 const result = await db.query(sql, params);
 ctx?.spans.push({ type: 'db', sql, duration: Date.now() - start });
 return result;
 } catch (err) {
 logger.info('Query failed', { sql, error: err.message });
 throw err;
 }
}

// Now every function in the request automatically logs with requestId
app.get('/users/:id', async (req, res) => {
 logger.info('Fetching user'); // requestId auto-included
 const user = await query( // span auto-recorded
 'SELECT * FROM users WHERE id = $1', [req.params.id]
 );
 logger.info('User fetched', { userId: user.id }); // requestId auto-included
 res.json(user);
});

const { createHook, executionAsyncId } = require('async_hooks');

// Track active async resources — spot resource leaks
const activeResources = new Map();

const hook = createHook({
 init(asyncId, type, triggerAsyncId) {
 activeResources.set(asyncId, { type, triggerAsyncId, created: Date.now() });
 },
 destroy(asyncId) {
 activeResources.delete(asyncId);
 },
 promiseResolve(asyncId) {
 activeResources.delete(asyncId);
 }
});
hook.enable();

// Check for resource leaks periodically
setInterval(() => {
 const now = Date.now();
 const old = [...activeResources.entries()]
 .filter(([, r]) => now - r.created > 10000) // Older than 10s
 .map(([id, r]) => `${r.type}(${id})`);
 if (old.length > 100) {
 console.warn('Possible resource leak:', old.length, 'old resources');
 }
}, 5000);