---
alwaysApply: false
globs: ["**/*"]
description: "One correlation identifier per request, from user-visible error to log and trace. Use when designing that identifier, not when adding logs or alerts."
---

# Request Correlation

**Produce exactly one correlation identifier per inbound request.** Create it
at the outermost boundary when the caller sent none. Accept the caller's
identifier when it exists, and keep both under separate names when both exist.
Use one field name for it in the whole system, and write that name down once.

**Propagate it across every boundary the request crosses.** Outbound calls,
queue messages, background jobs the request starts, and database statements
where the driver carries a comment. A boundary that drops the identifier
breaks the chain, and a broken chain is a defect, not a gap.

**Write it into three places.** Into every log line the request produces, onto
the trace or span for the request, and into the text the user sees when the
request fails. The user-visible text carries the identifier and no other
technical detail: "Booking failed. Nothing was reserved. Please call us and
say code 7F3A-2B."

**Make the identifier quotable by a person.** Short enough to read over the
phone, from an alphabet without look-alike characters, and containing no name,
address, e-mail or account number. Print it in the same format everywhere, so
an operator can search for the string a customer read out.

**Produce the retrieval path together with the identifier.** Write down, in
the operator documentation, the one query that turns an identifier into that
request's log lines and trace. An identifier nobody can search is decoration.

**A reviewer checks:**

- take any failure text a user could quote, and from its identifier alone
  retrieve that request's log line and its trace — with no code change, no
  redeploy, and no guess at the time window;
- one request produces one identifier, not one per service;
- the identifier survives every queue, job and outbound call in the path;
- the identifier holds no personal data and no secret;
- the written retrieval query works as written.

**Boundary.** What to log, which metrics to emit, and which conditions raise
an alert belong to the observability-coding skill, which fires when logging,
metrics or alerts are being added. This skill owns one narrower thing: the
single identifier that ties one human report to one request.