How to read a request waterfall

RED tells you a route got slower. A waterfall tells you where the time went. That distinction is the difference between watching a chart and shipping a fix.

The problem

p95 latency is a distribution, not a story. A checkout that jumped from 200ms to 1.8s might be one sequential query, a burst of identical selects (N+1), or a payment API that started waiting on you. Aggregates cannot name the culprit. A single sampled trace can.

What it is

A waterfall plots each span as a bar on a shared time axis. Indentation (or a parent pointer) shows nesting. The root is the transaction — typically POST /checkout or a browser pageload. Children start after their parent and should end before it. Gaps in the root that no child covers are time in your own code, GC, or work you did not instrument.

The critical path is the longest chain of dependent spans from start to finish. Parallel children that sit under the same parent do not add; sequential children do. Optimize the critical path first. Speeding a span that is not on it will not move p95.

What it gives a team

• A shared artifact in standup: one trace, not a screenshot of four dashboards.
• Error and N+1 badges on the spans that deserve them, so you do not hunt through a quiet tree.
• A jump from an event or issue that carries traceId — View trace on the event opens this page.

How Talaria does it

The dashboard route is Performance → a transaction row → Trace (/projects/:id/performance/traces/:traceId). The API is SpansEndpoint.getTrace, which loads a bundle of spans for that ID. Duration bars, parent/child layout, error status, and N+1 flags are rendered from that bundle.

N+1 is flagged at ingest when the same db.query.text repeats at least ten times in one trace — a heuristic, not ORM intelligence. See slow queries and N+1.

The waterfall loads up to 500 spans for a trace, and ingest stores up to 200 child spans per transaction — enough depth for the tree you would actually read.

How to read it

• Confirm the root name and status. An error root is a failed request, not just a slow one.
• Find the longest child. If it is HTTP, open Dependencies for that peer’s error rate and p95.
• If many short DB bars stack, look for the N+1 badge before rewriting indexes.
• If children are thin and the root is still long, the time is in uninstrumented code — or the client waiting on bytes you have not measured here.

A waterfall is one sampled request. Use RED to see the shape of traffic and a waterfall to explain one request.

Turn it on

Waterfalls exist only for sampled traces. Opt into tracing on the SDK, then open a transaction from Performance. Error transactions are always sampled once tracing is enabled, which is why the first useful waterfall is often the one attached to an issue.