Correlation IDs: Trace a Single Request Across Every Service in Your API

The Problem: One Request, Five Services, Zero Clues

A user reports that "saving their profile failed." You open your logs and find a 500. But that single request touched your API gateway, an auth service, a profile service, and a database proxy. Each one logged something — but nothing ties those lines together. You're left grepping by timestamp and praying no one else made a request in the same second.

A correlation ID (also called a request ID or trace ID) fixes this. It's a single unique value attached to a request when it enters your system and propagated to every downstream call and log line. One ID, one full story.

Step 1: Accept or Generate the ID at the Edge

The rule: if an incoming request already carries a correlation ID header, reuse it. If not, generate one. This lets clients and upstream services thread their own IDs through your stack.

Here's an Express middleware that does exactly that:

import { randomUUID } from "node:crypto";
import { AsyncLocalStorage } from "node:async_hooks";

export const requestContext = new AsyncLocalStorage();

export function correlationId(req, res, next) {
  const incoming = req.header("x-correlation-id");
  const id = incoming || randomUUID();

  // Echo it back so clients can log it too
  res.setHeader("x-correlation-id", id);

  // Make it available anywhere in this request, no prop-drilling
  requestContext.run({ correlationId: id }, () => next());
}

AsyncLocalStorage is the key trick: it gives you per-request storage that survives async/await without passing req into every function.

Step 2: Put the ID in Every Log Line

A correlation ID is worthless if it isn't in your logs. Wrap your logger so it reads from context automatically:

function log(level, message, meta = {}) {
  const store = requestContext.getStore();
  console.log(JSON.stringify({
    level,
    message,
    correlationId: store?.correlationId ?? "none",
    timestamp: new Date().toISOString(),
    ...meta,
  }));
}

// Anywhere in your code — no need to pass the ID around:
log("info", "profile updated", { userId: 42 });
// {"level":"info","message":"profile updated","correlationId":"a1b2...","userId":42,...}

Now a single grep (or a Loki/Datadog filter) on the ID returns every line for that request, in order.

Step 3: Propagate Downstream

The ID has to ride along on every outbound call, or the trail dies at your service boundary. Patch your HTTP client to inject it:

async function fetchWithTrace(url, options = {}) {
  const store = requestContext.getStore();
  const headers = {
    ...options.headers,
    "x-correlation-id": store?.correlationId ?? randomUUID(),
  };
  return fetch(url, { ...options, headers });
}

// The downstream service's own middleware will pick this up and reuse it.
await fetchWithTrace("https://billing.internal/charge", {
  method: "POST",
  body: JSON.stringify({ amount: 999 }),
});

Do the same for message queues — put the ID in the message metadata so async consumers stay on the same trace.

Step 4: Return It to the Client

Always expose the ID in responses (we did this with res.setHeader above) and in error bodies:

app.use((err, req, res, next) => {
  const id = requestContext.getStore()?.correlationId;
  log("error", err.message, { stack: err.stack });
  res.status(500).json({
    error: "internal_server_error",
    correlationId: id,
  });
});

Now when a user files a bug, they can paste the ID straight from the error response. You go from "saving failed" to the exact failing line in seconds.

A Few Practical Rules

Pick one header name and standardize it everywhere — x-correlation-id, x-request-id, or the W3C traceparent if you're adopting OpenTelemetry. Don't trust client-supplied IDs blindly: cap their length and strip anything that isn't alphanumeric/hyphen to avoid log-injection. And keep the ID opaque — it's for correlation, not for carrying user data.

Wrapping Up

Correlation IDs are one of the highest-leverage, lowest-effort changes you can make to an API: a few lines of middleware turn scattered, unjoinable logs into a single searchable thread per request. Generate at the edge, store in context, log everywhere, propagate downstream, and return it to the caller.

If you'd rather see correlation IDs flow through your endpoints without hand-rolling the plumbing, APIKumo lets you set request/response headers and pre/post-processors across an entire API collection — so you can inject and inspect trace headers on every call, share live docs that document them, and debug multi-service requests from one workspace.

推荐订阅源

DEV Community