What Is a Correlation ID?

Last verified on Nov 8, 2026.

A correlation ID is a unique value attached to a request, or to a longer workflow, and written into every log line produced along the way. Given one ID, a log search returns the lines from every service that handled the request, in order. It is one of the simplest ways to follow work across a distributed system.

Common Examples

Several platforms already generate one for you:

None of the first three is part of the W3C standard. Each has its own format, and your stack may carry several at once.

Correlation ID vs Trace ID

A correlation ID is a convention you choose. A trace ID is a standard identifier with a defined format: 32 lowercase hex characters, passed in traceparent. The practical difference is what comes with it. A trace ID also identifies spans with timing and parent-child structure, and OpenTelemetry SDKs can inject it into log records for you.

OpenTelemetry's logs specification lists three ways logs can be correlated: by time, by execution context (trace and span IDs), and by the origin of the telemetry. A correlation ID is a hand-built version of the second. If you already run tracing, log the trace ID and treat it as your correlation ID. If you do not, a request ID is a good first step, and it works with any structured logging setup.

How to Implement One

1. Accept or create at the edge. Take the ID from an incoming header if it is well formed, or generate one. Heroku's rule is a useful model: an inbound value must be 20 to 200 characters from a safe set, and invalid values are replaced.
2. Store it per request. Use request-scoped storage so every log call sees the ID without passing it around.
3. Log it on every line, as a field named consistently, such as request_id.
4. Return it in the response header, so a user or support engineer can quote it.
5. Forward it on every outgoing call, including queue messages and background jobs.

This Node.js example uses AsyncLocalStorage and was run against three requests: no header, a malformed one, and a valid one. The first two got new UUIDs, and the third kept its ID:

const http = require('node:http')
const { AsyncLocalStorage } = require('node:async_hooks')
const { randomUUID } = require('node:crypto')

const store = new AsyncLocalStorage()
const VALID = /^[A-Za-z0-9+\/=-]{20,200}$/

function log(msg, fields = {}) {
  console.log(JSON.stringify({ msg, request_id: store.getStore(), ...fields }))
}

http
  .createServer((req, res) => {
    const inbound = req.headers['x-request-id']
    const id = inbound && VALID.test(inbound) ? inbound : randomUUID()
    res.setHeader('x-request-id', id)
    store.run(id, () => {
      log('request received', { path: req.url })
      res.end('ok\n')
    })
  })
  .listen(8080)

To follow one request in JSON logs from a file, filter on the field:

jq -c 'select(.request_id == "req-1234567890-abcdefghij")' app.log

Pitfalls

• Trusting outside values. An ID from the public internet can be forged or stuffed with junk. Validate length and characters before logging it. OpenTelemetry gives similar advice for trace context from external sources.
• IDs that stop at a boundary. Queues, cron jobs, and webhooks are where the chain usually breaks. Put the ID in the message or job payload.
• Different names per service. requestId, req_id, and x-correlation-id in different services mean a search misses lines. Pick one field name and use it everywhere. The logging best practices guide covers shared fields.
• Personal data in the ID. Use a random value, not an email or user ID. OpenTelemetry also warns that baggage values can end up in logs.

See the microservices logging guide for patterns across services.

Correlation IDs in Sazabi

Sazabi, an AI-native observability and security platform, lets you ask about your logs in plain language, and its traces docs describe searching by trace ID to pull spans and correlated log lines together. A request ID or trace ID in your records gives that search something to hold on to. The log search docs cover sazabi logs ask. If you use Cloudflare, see the Cloudflare integration and Cloudflare's documentation on adding Cf-Ray to origin logs. For trace IDs, see the OpenTelemetry traces setup.