About this block

Trace Waterfall is the span timeline for a single distributed trace, trc_9f3ab21c, captured at 09:41:22 UTC with a total of 842 ms. The header pairs a 1 error badge and an 842 ms total badge with View logs and Share actions. Eight spans render as rows under a shared time axis marked 0 ms to 840: the root GET /api/checkout on edge-gateway holds the full width, and nested spans for auth.verify, cart.load, pricing.calculate, and their database and cache calls are offset and sized against the same clock. The final span, payment.authorize on the payments service, carries a destructive tint and a footer note that card_declined came back from the upstream processor after 2 attempts.

Each span is a typed record with left and width percent values and an error flag, so the bars position purely from data. The failing span swaps its bar and duration colour to the destructive token rather than adding a separate marker.

When to use

Reach for this block on an observability or developer tools page, wired to your tracing backend and keyed to a trace id. Link each span to its logs and let the footer band surface the first error so an engineer lands on the failing call without scanning every row.

A natural flow around it on an Application Pro page:

Before

• Log viewer
• App shell

After

• Status and health
• Integrations

What you can display

One strong use is the request trace waterfall. Other timeline shapes:

• Frontend trace. Swap services for page, script, and paint phases to profile a slow route render.
• Job pipeline. Map each span to a queued job and show retries and wait time between stages.
• Database trace. Break one query into parse, plan, and execute spans to find where the time goes.

Tip: keep every bar on one shared axis; the offset is what shows which spans overlap and which block.