How can I automatically inject correlation IDs into Winston logs in my Express/TypeScript app?

Below is one approach to achieve what you want using Node’s built-in asynchronous context propagation with AsyncLocalStorage. This lets you “store” the correlation id in a context that is accessible to any subsequent code (even deep in services) without having to explicitly pass it around.

Below are the steps and code examples:

---

1. Create an AsyncLocalStorage Instance

Create a file (e.g., asyncLocalStorage.ts) to export a shared AsyncLocalStorage instance:

TYPESCRIPTCopied
// asyncLocalStorage.ts
import { AsyncLocalStorage } from "async_hooks";

export const asyncLocalStorage = new AsyncLocalStorage<Map<string, any>>();

---

2. Update the Correlation Middleware

Wrap each incoming request in an AsyncLocalStorage run block. This middleware sets the correlation id (from the header or generates a new one) and stores it in the async local store.

TYPESCRIPTCopied
// correlationMiddleware.ts
import { Request, Response, NextFunction } from "express";
import { v4 as uuidv4 } from "uuid";
import { asyncLocalStorage } from "./asyncLocalStorage";

const correlationIdMiddleware = (
  req: Request,
  res: Response,
  next: NextFunction
): void => {
  const correlationIdHeader = req.headers["x-correlation-id"];
  const correlationId = Array.isArray(correlationIdHeader)
    ? correlationIdHeader[0]
    : correlationIdHeader || uuidv4();

  req.correlationId = correlationId;
  res.setHeader("x-correlation-id", correlationId);

  // Create a new store and run the request within that context.
  const store = new Map<string, any>();
  store.set("correlationId", correlationId);
  asyncLocalStorage.run(store, () => {
    next();
  });
};

export default correlationIdMiddleware;

Make sure to add this middleware early in your middleware chain so that all subsequent processing (including in services) can access the correlation id.

---

3. Update the Logger to Inject the Correlation Id

Use a custom Winston format to add the correlation id from AsyncLocalStorage to all log entries.

TYPESCRIPTCopied
// logger.ts
import winston from "winston";
import "winston-mongodb";
import sanitizedConfig from "../config";
import { asyncLocalStorage } from "./asyncLocalStorage";

const levels = {
  error: 0,
  warn: 1,
  info: 2,
  http: 3,
  debug: 4,
};

const level = (): string => {
  const env = process.env.NODE_ENV || "development";
  const isDevelopment = env === "development";
  return isDevelopment ? "debug" : "warn";
};

const colors = {
  error: "red",
  warn: "yellow",
  info: "green",
  http: "magenta",
  debug: "white",
};

winston.addColors(colors);

// Custom format that injects correlation id from the async local store.
const addCorrelationId = winston.format((info) => {
  const store = asyncLocalStorage.getStore();
  if (store && store.get("correlationId")) {
    info.correlationId = store.get("correlationId");
  }
  return info;
});

// Custom printf format that prints out the timestamp, log level, correlation id, and message.
const customPrintf = winston.format.printf((info) => {
  return `${info.timestamp} ${info.level}: [${info.correlationId || "N/A"}] ${info.message}`;
});

const format = winston.format.combine(
  addCorrelationId(),
  winston.format.timestamp({ format: "YYYY-MM-DD HH:mm:ss.SSS" }),
  customPrintf
);

const mongoTransport = new winston.transports.MongoDB({
  db: sanitizedConfig.DB_URL,
  collection: "logs",
  level: "debug",
  format: winston.format.combine(
    addCorrelationId(),
    winston.format.timestamp(),
    winston.format.json()
  ),
});

const consoleTransport = new winston.transports.Console({
  format: winston.format.combine(
    winston.format.colorize({ all: true }),
    customPrintf
  ),
});

const Logger = winston.createLogger({
  level: level(),
  levels,
  format,
  transports: [consoleTransport, mongoTransport],
});

export default Logger;

Now any call to your logger (e.g., in a controller):

TYPESCRIPTCopied
Logger.info(`User ${user.id} updated successfully`);

will automatically include the correlation id in the log message from both the console and MongoDB.

---

How It Works

1. Correlation Middleware: Every request gets a correlation id (from header or generated). The request is wrapped inside asyncLocalStorage.run(), setting the correlation id in the store.
2. Logger Custom Format: A custom Winston format (addCorrelationId) looks up the correlation id from the async store. If found, it attaches it to the log info.
3. Global Availability: Since AsyncLocalStorage persists through async calls, even logs inside services (e.g., in your sendMail function) will include the current request’s correlation id.

This solution allows you to centrally manage the correlation id inclusion in logs without having to manually pass it around in every function call.