Logging and Observability Middleware

In this lesson, you will learn how to implement correlation IDs to trace a single user request across your entire distributed system.

The Problem: Identifying the "Needle in the Haystack"

In a stateless server architecture, a single user action might trigger multiple logs across different services or even different asynchronous execution blocks. If a user reports a bug, searching through logs for their specific sequence of events is nearly impossible if you only have timestamps or IP addresses.

To solve this, we use Correlation IDs. A correlation ID is a unique string (often a UUID) generated the moment a request hits your server. By attaching this ID to every log entry produced during that request's lifecycle, you can filter your logs to see exactly what happened for that specific transaction.

Implementing Correlation IDs

We can implement this using a custom middleware that runs at the very beginning of the request lifecycle. The middleware generates an ID and attaches it to the request object, making it available to all subsequent middleware and route handlers.

const { v4: uuidv4 } = require('uuid');

const correlationMiddleware = (req, res, next) => {
  // Generate a unique ID for this request
  const correlationId = req.headers['x-correlation-id'] || uuidv4();
  
  // Attach it to the request so other parts of the app can access it
  req.correlationId = correlationId;
  
  // Add it to the response headers so the client/upstream knows the ID
  res.setHeader('x-correlation-id', correlationId);
  
  next();
};

Once the ID is attached to req, any logging utility you use should be configured to pull req.correlationId and include it in every log output. For example:

app.use((req, res, next) => {
  console.log(`[${req.correlationId}] Received ${req.method} request for ${req.url}`);
  next();
});

By ensuring that every database query, third-party API call, or error log includes this correlationId in the metadata, you transform an unorganized pile of logs into a coherent narrative of a single request’s journey through your system.

Key Takeaway: Injecting a unique correlation ID at the start of your middleware chain creates a traceable "thread" that links all logs associated with a single request across your entire infrastructure.