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 GET /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.

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.

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.

What this is not

The waterfall loads at most 500 spans for a trace. Ingest caps children at 200 per transaction. There is no span-detail drawer beyond the tree, no flame graph, and no span-to-log correlation — Talaria is not a log platform.