caliper uidocs
DemoSign inGet Pro

Trace waterfall

Pro

A distributed trace as a waterfall: spans nested by parent, coloured by service, errors marked, the critical path on demand, zoom to any span, search by name or service, and the selected span’s attributes beside it.

Installs components/ui/trace-waterfall.tsxDepends on @radix-ui/react-slot, lucide-reactMotion shared motion tokens
pnpm dlx shadcn@latest add @caliper/trace-waterfall

Trace 4bf92f35

842 ms · 12 spans · 7 services · 1 error
  • gateway
  • auth
  • billing
  • postgres
  • tax
  • renderer
  • queue
POST /api/invoicesgateway842 ms
auth.verifyauth38 ms
invoices.createbilling770 ms
SELECT customerspostgres22 ms
tax.quotetax312 ms
GET vatstack /ratestax140 ms
GET vatstack /rates (retry)tax152 ms
INSERT invoicespostgres31 ms
pdf.renderrenderer356 ms
fonts.loadrenderer64 ms
queue.publish invoice.createdqueue12 ms
audit.writeauth14 ms

↑ ↓ move · ← → collapse and expand · Enter selects

When to use #

Use it for

  • APM, observability and developer platforms.
  • Explaining why one request was slow.

Skip it when

  • A flat list of log lines; use the log explorer.

Installation #

terminal
pnpm dlx shadcn@latest add @caliper/trace-waterfall

Adds its 8 files to components/ui/, each with its own stylesheet, and installs their packages. Pro installs with your access token, set up once per project. See Pro access. The first part also adds Caliper UI’s tokens; import them once as in Installation.

Usage #

Import it from your copy of the source. The example behind the preview comes with the source. It is built from formatMs, criticalSpans and TraceWaterfall.

example.tsx
import { formatMs, criticalSpans, TraceWaterfall } from "@/components/ui/trace-waterfall"

The worked example comes with Pro

The 25-line example behind the preview opens here with a Pro or Team licence.

Checking your licence…

API reference #

formatMs

component

No props of its own; it accepts the native props of its root element.

criticalSpans

component

No props of its own; it accepts the native props of its root element.

TraceWaterfall

component
PropTypeDefaultDescription
spans *readonly TraceSpan[]—
labelstring"Trace"
columnsreadonly TraceColumn[][]Extra columns beside each span's name, e.g. tokens or cost.
detail((span: TraceSpan) => ReactNode)—More detail for the selected span, under its attributes.
selectedstring | null—
onSelect((id: string | null) => void)—
classNamestring—

Accessibility #

It exposes treegrid, row and gridcell semantics, with aria-labelledby, aria-hidden, aria-label, aria-describedby, aria-level and aria-expanded kept in step with state.

KeyBehaviour
↓Moves to the next item or value.
↑Moves to the previous item or value.
→Moves to the next item or value.
←Moves to the previous item or value.
EnterActivates the focused control.
SpaceActivates the focused control.
HomeJumps to the first item or the minimum.
EndJumps to the last item or the maximum.

Motion #

Transitions use the shared duration and easing tokens. Under prefers-reduced-motion those tokens collapse to instant and travel distances go to zero, so state changes still happen without movement.