AddThisFeature

Request Correlation IDs

Follow one user action through every request, job, and downstream call.

moderate Developer Experience

What it adds

A single ID generated or accepted at the edge and carried through logs, background jobs, outbound calls, and error reports, so one user action can be reconstructed end to end.

What your agent is told to do

6
  1. 1

    Generate a correlation ID at the entry point of every inbound request. If the caller supplied one, validate it before trusting it — bounded length, a restricted character set, no newlines — and generate a fresh one if it fails.

  2. 2

    Store the ID in a context that follows the unit of work, not in a global variable. Concurrent requests must never share one.

  3. 3

    Propagate it explicitly: attach it to every log line, enqueue it with every background job, send it as a header on every outbound HTTP call, and attach it to error-tracker reports.

  4. 4

    Show the ID on user-facing error pages so a support ticket can be matched to the exact failure. Show only the ID — never the exception, the stack, or the internal service that failed.

  5. 5

    Do NOT derive the ID from user data, session tokens, or sequential counters. It must be unguessable and it must reveal nothing about who the user is.

  6. 6

    Field names, severity levels, and redaction rules are owned by Structured Logging; extend that schema with the correlation field rather than defining a second logging convention here.

Edge cases it handles

6
  • A job that spawns further jobs must pass the ID down the chain, and a retry must reuse the original ID rather than minting a new one.
  • Scheduled and cron-triggered work has no inbound request. Generate an ID at the start of the run so those events are still traceable.
  • An untrusted inbound header must never be echoed back unvalidated — that is a header injection and log-forging path.
  • Async work that outlives the request must not lose the context when the request completes.
  • The ID must appear in the response headers so a client or proxy can record it without reading the page.
  • Do not let a missing ID be an error. If context is unavailable for any reason, log with a placeholder and continue serving.

Definition of done

8
  • Every inbound request has a correlation ID, either validated from the caller or freshly generated.
  • The ID appears on every log line produced during that request.
  • Background jobs, retries, and outbound HTTP calls carry the same ID.
  • Error-tracker reports are tagged with the ID and user-facing error pages display it.
  • The ID is returned in a response header.
  • IDs contain no user-identifying or sequential information.
  • The feature matches the existing design system.
  • No existing functionality is broken.

Related features

How it works

  1. 1

    Copy the link

    Grab the Markdown instruction URL for this feature.

  2. 2

    Give it to your AI

    Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.

  3. 3

    It inspects, then implements

    Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.