Back to guides

Guide · Observability

How to Implement Request ID Tracing

Request ID tracing lets you follow a request across services and logs. Here's how to implement it.

Request IDs are the backbone of Observability across model, tool, and API spans. Primary control: Observability

One ID to find the needle

When a user says "payment failed," you need every log line for that attempt—not a timestamp guess across millions of rows. A request ID (correlation ID) is minted at the edge, propagated everywhere, and written into structured logs. That is baseline APRF Observability.

Without IDs, one team searched by clock and user and hoped. With `request_id=abc123`, the same failure was a single search.

Wire it end to end

1. Generate a UUID in edge middleware; set `X-Request-ID` (pick one name and keep it)

2. Forward the header to every HTTP hop and into queue/async payloads

3. Include `request_id` in every JSON log line

4. Echo it on error responses so support can ask for it

5. For AI paths, carry the same ID on model/tool spans

Libraries like `express-request-id` plus Winston/Pino make the boring parts cheap. Search in CloudWatch or Datadog by that field.

Don't drop the thread

Async workers that mint a new ID break the story. Inconsistent header names do too. Treat missing propagation as a bug in code review—the same bar as forgetting auth on a route.

Next: Observability

Open the related pillar specification for mandatory checks, artifacts, and pass conditions. Self-attest is optional.

View ObservabilitySelf-attest

Related

Frequently asked questions

How do I implement request ID tracing?
Generate a UUID at the edge (middleware). Pass it in HTTP headers to downstream services. Include it in every log entry. Return it in error responses for support.
What is request ID tracing?
A unique ID per request that you pass through all services and include in logs. Lets you find all logs for a single request in seconds.
Should I use X-Request-ID or X-Correlation-ID?
Either works. Use one consistently. X-Request-ID is common. Pass it to all downstream services and async jobs.