Correlation ID Debugger
One ID, minted at the frontend and propagated through every hop. Watch a video-watermark request fail deep in an AWS pipeline — then watch an AI agent use that single ID to trace the 401 straight to its root cause.
- One ID, every service
- AI agent root-cause trace
- Runs 100% in your browser
Trace a distributed failure end to end
Hit Submit to mint a correlation ID, watch a video-watermark request stream through nine services, fail at an authorize-protected Lambda, and see an AI agent trace the 401 straight to its root cause.
What a correlation ID actually buys you
In a monolith, a stack trace tells you where a request broke. In a distributed system — a frontend, an event bus, a state machine, and half a dozen Lambdas — there is no single stack trace. The request hops across process boundaries, and each service writes to its own log group. When something fails three hops deep, the user sees a generic error and you are left cross-referencing six log groups by timestamp, guessing which lines belong to the same request.
A correlation ID fixes that. You generate one unique value when the request begins and propagate it — as a header, an event field, a log attribute, and a database column — through every service it touches. Now a single query filter correlationId = "…" reassembles the entire request as one ordered timeline. This tool makes that power visceral: it simulates a real pipeline failure and shows you both worlds — with the ID, and without it.
The bug: a header the router forgot to forward
A user submits a video to be watermarked. The frontend uploads it to S3, which fires an S3 upload notification Lambda that publishes a video.uploaded event to EventBridge. A rule starts a Step Functions state machine, which invokes the ffprobe metadata Lambda, then the router (determine-compress-strategy) that inspects the metadata and routes to the right watermarking strategy — multi-chunk decompress for large files, direct decompress for small ones.
The watermark Lambdas are authorize-protected: their internal metadata API requires an Authorization header. The router invokes the watermark Lambda but forwards only X-Correlation-Id — not Authorization. So when the watermark Lambda makes its own GET /internal/metadata call, it has no credentials to pass along and the request is rejected with 401 Unauthorized. The pipeline fails, Supabase records status='failed', and the frontend shows a generic “please try again.”
How the AI agent finds it
- 1
Hit “Submit watermark request.” The tool mints a correlation ID at the frontend — exactly as a real app would with crypto.randomUUID() — and attaches it as an X-Correlation-Id header.
- 2
The request streams through nine services: S3 upload notification → EventBridge → a Step Functions state machine → the ffprobe metadata Lambda → the router (determine-compress-strategy) → an authorize-protected watermark Lambda → Supabase → back to the frontend. Every log line carries the same ID.
- 3
The router forgets to forward the Authorization header when it invokes the watermark Lambda, so the watermark Lambda’s internal GET /internal/metadata is rejected with 401 Unauthorized. The frontend shows only a generic error.
- 4
Watch the AI agent filter CloudWatch Logs Insights by that one correlation ID, collapse six log groups into a single ordered trace, diff the two /internal/metadata calls, and pin the root cause to the router’s missing header — then copy the one-line fix.
Frequently asked questions
What is a correlation ID?
A correlation ID (also called a request ID or trace ID) is a unique value generated once — usually at the edge, when a user action begins — and then propagated unchanged through every service, queue, function, and log line that the request touches. Because the same ID appears everywhere, you can reconstruct the entire causal path of a single request across an otherwise disconnected set of services by filtering logs on that one value.
How does an AI agent use a correlation ID to debug a failure?
When a request fails deep in a distributed system, the surface error is usually generic. The one durable clue is the correlation ID persisted alongside the failed record. An AI agent (or a human) runs a single CloudWatch Logs Insights query — filter correlationId = "…" | sort @timestamp asc — which merges every service’s log group into one ordered timeline. It finds the error span, walks the parent chain upward by the same ID, diffs the healthy call against the failing one, and pinpoints exactly where the request went wrong. Without a shared ID, those log lines are scattered across services with no way to link them.
Correlation ID vs trace ID — what is the difference?
They overlap heavily. In OpenTelemetry and distributed-tracing tooling, a trace ID identifies one end-to-end trace and each hop gets its own span ID. A correlation ID is the broader, framework-agnostic idea: any single value you thread through logs, headers, events, and database rows to tie a request together. In practice you often reuse the trace ID as your correlation ID and log it as a structured field so both your tracing backend and your log search can key on it.
How do you propagate a correlation ID across Lambda, Step Functions, and EventBridge?
Generate it once at the frontend and send it as a header (X-Correlation-Id). At each boundary, read it and carry it forward: an API route reads the header and puts it into the EventBridge event detail; EventBridge passes the detail into the Step Functions execution input; each Lambda reads it from the event (event.headers or event.detail.correlationId), binds it to its logger so every line is auto-tagged, and — critically — forwards it (plus any auth headers) on every downstream invoke or HTTP call. The bug this tool demonstrates is a broken hop: the router forwards the correlation ID but forgets to forward the Authorization header.
Why did the watermark Lambda return 401 Unauthorized?
The watermark Lambdas are authorize-protected: their internal metadata API requires an Authorization header. The router Lambda invokes the watermark Lambda but only forwards X-Correlation-Id, not Authorization. So when the watermark Lambda makes its own GET /internal/metadata call, it has no credentials to pass along and the request is rejected with 401. The ffprobe Lambda earlier in the pipeline made the identical call successfully because it still had its Authorization header — diffing those two calls is exactly how the agent isolates the root cause.
Is anything uploaded when I use this tool?
No. The entire simulation runs client-side in your browser. There is no real AWS pipeline, no video upload, and nothing sent to a server — the trace, logs, and investigation are generated locally and deterministically from the options you choose.
More developer tools
Browse the full set of free, browser-based developer tools from jsmanifest, or read the latest JavaScript and TypeScript articles.