Trace Waterfall | drift-ui

@drift-ui/trace-waterfallRegistry JSON GitHub Open in v0

POST /checkout320 ms · 6 spans · 5 services · 1 error

api-gateway
inventory-svc
postgres
payment-svc
mailer
error

Span

0 ms100 ms200 ms300 ms

POST /checkoutapi-gateway320 ms

jwt.verifyapi-gateway28 ms

inventory.checkStockinventory-svc65 ms

SELECT items FROM inventorypostgres48 ms

stripe.chargepayment-svc140 ms

email.sendConfirmationmailer45 ms

stripe.charge

payment-svc

Duration: 140 ms
Share of trace: 43.8%
Starts at: +115 ms
Status: error
Span ID: payment

error.type: card_declined
stripe.request_id: req_8Fq2LxN0

Keyboard

↑↓: Move between spans
→: Expand, then enter children
←: Collapse, then go to the parent
HomeEnd: First or last span
EnterSpace: Select or deselect the span

The CLI also installs the npm packages and registry items it builds on, and reads the style in your components.json to pick the Base UI or Radix build.

trace-waterfall-usage.tsx

import { TraceWaterfall, type Span } from "@/components/ui/trace-waterfall"

const spans: Span[] = [
  { id: "1", name: "GET /orders", start: 0, duration: 240, service: "gateway" },
  { id: "2", parentId: "1", name: "SELECT orders", start: 18, duration: 90, status: "error", service: "postgres" },
]

export function RequestTrace() {
  return <TraceWaterfall spans={spans} />
}

TraceWaterfall

Waterfall timeline displaying distributed request spans as a collapsible tree and duration bars on a shared time axis.

Prop	Type	Default
`spans`Required`Span[]`Array of trace spans with id, parentId?, name, start, duration, status?, service?, color?, attributes?: Record<string, string \| number \| boolean>.	`Span[]`
`selectedSpanIdstring \| null`Controlled id of the selected span.	`string \| null`
`defaultSelectedSpanIdstring \| null`Default`null`Initially selected span id when uncontrolled.	`string \| null`	`null`
`onSpanSelect(span: Span \| null) => void`Called when a span is selected or deselected.	`(span: Span \| null) => void`
`expandedSpanIdsstring[]`Controlled ids of open branches.	`string[]`
`defaultExpandedSpanIdsstring[]`Default`all parent spans`Initially expanded branch ids when uncontrolled.	`string[]`	`all parent spans`
`onExpandedChange(expandedIds: string[]) => void`Called when a branch opens or closes.	`(expandedIds: string[]) => void`
`formatTime(ms: number) => string`Default`formatDuration`Formats millisecond values for ruler ticks, row durations and the details panel.	`(ms: number) => string`	`formatDuration`
`minBarWidthnumber`Default`4`Minimum pixel width for bars, ensuring zero-duration spans remain visible.	`number`	`4`
`showTimeAxisboolean`Default`true`Renders the top timeline ruler with time intervals.	`boolean`	`true`
`showGridLinesboolean`Default`true`Renders vertical alignment grid lines across rows matching ruler ticks.	`boolean`	`true`
`showSpanDetailsboolean`Default`true`Shows a panel under the waterfall with the selected span's timing, status and attributes. Turn off when you render your own panel from onSpanSelect.	`boolean`	`true`

Other props go to the <div>.

Request trace

Visualizes the call tree and execution timeline of an API request across database and service boundaries.

GET /api/v1/users180 ms · 5 spans · 4 services

web
auth
user-svc
db

Span

0 ms50 ms100 ms150 ms

GET /api/v1/usersweb180 ms

authenticateauth20 ms

findUsersuser-svc110 ms

SELECT * FROM users LIMIT 50db85 ms

serializeResponseweb25 ms

Selection and inspection

Control expanded branches and inspect the active span when clicked or activated via keyboard.

Click a span or press Enter to inspect

Build & Deploy Pipeline12.5 s · 5 spans · 5 services

ci-runner
linter
test-suite
compiler
deployer

Span

0 ms2.5 s5 s7.5 s10 s12.5 s

Build & Deploy Pipelineci-runner12.5 s

eslint && prettierlinter1.8 s

vitest runtest-suite4.6 s

next buildcompiler3.8 s

docker pushdeployer1.6 s

Errors and zero-duration events

Highlights failed operations with destructive status styling and renders zero-duration checkpoint events with a visible marker.

POST /api/charge410 ms · 5 spans · 4 services · 3 errors

api-server
auth
postgres
payment-gateway
error

Span

0 ms100 ms200 ms300 ms400 ms

POST /api/chargeapi-server410 ms

verifyCustomerauth35 ms

acquireDbConnectionpostgres120 ms

gateway.chargeCardpayment-gateway230 ms

webhook.timeoutpayment-gateway0 ms

components/ui/trace-waterfall.tsx