TraceWaterfall

Chart

Inspect nested trace spans on one timeline with collapsible branches, explicit failure markers, and compressed idle gaps that preserve reported durations.

Related docs

bun add @reopt-ai/opt-charts

Install and import

bash

bun add @reopt-ai/opt-charts

tsx

import { TraceWaterfall } from "@reopt-ai/opt-charts";

Live preview

Change the width and theme, then interact with the components.

100%

에이전트 턴 트레이스

↑/↓로 행 이동, ←/→로 접기·펼치기, Enter 또는 Space로 선택합니다. 접힌 시간축에서도 소요 시간은 실제 값입니다.

유휴 구간 접기

승인을 기다린 2분을 접지 않으면 380ms 도구 호출이 점이 된다

embedding
generation
tool
trace

배송 문의

4.20s

gpt-5

입력 1,850 · 출력 240 · $0.0054

2.90s

lookup_order

380ms

text-embedding-3-small

160ms

배송 문의

3.10s

claude-sonnet-4-5

입력 3,120 · 출력 480 · $0.0081

3.00s

claude-haiku-4-5

APICallError · 529

1.00s

선택: gpt-5

입력 1,850 · 출력 240 · $0.0054

상태: 정상

좁은 패널과 빈 트레이스

embedding
generation
tool
trace

배송 문의

4.20s

gpt-5

입력 1,850 · 출력 240 · $0.0054

2.90s

lookup_order

380ms

text-embedding-3-small

160ms

배송 문의

3.10s

claude-sonnet-4-5

입력 3,120 · 출력 480 · $0.0081

3.00s

claude-haiku-4-5

APICallError · 529

1.00s

아직 수집된 스팬이 없습니다.

Usage guidance

Anatomy

Axis with folded idle intervals → span rows with indentation, collapse toggles, and names → duration bars with hatched idle intervals → elapsed time

Best practices

Use when spans in a trace need to be read by both chronology and parent-child relationships. Supply startMs/endMs as absolute epoch milliseconds; the component sets the axis.
Use kind to distinguish generation, tool, and embedding spans with automatic colors. Override specific colors with kindColors.
Share selection with a details panel through onSelect and selectedId. Clicking either the name or the bar selects the same span.
For more than a few hundred spans, limit rows with maxRows and provide a link to a list page.

Usage to avoid

Use GanttChart for schedules and roadmaps.
Disabling folding can reduce short calls to tiny dots when a trace contains long idle intervals. Disable it only when a true time scale is required.

Usage examples

Agent turn trace

TraceWaterfall

Prop	Type	Default	Description
spansRequired	TraceSpan[]	—	{ id, parentId?, name, startMs, endMs?, durationMs?, kind?, status?, detail?, disabled? } 목록. id는 고유해야 하며 시간은 절대 epoch ms. endMs가 없으면 durationMs를 사용하고 둘 다 없으면 순간 이벤트로 표시
folding	TraceWaterfallFolding \| false	—	{ ratio?: 0..1, ms?: number, markerWidth?: 0..1, maxTotal?: 0..1 }. 기본값은 각각 0.2, 10000, 0.08, 0.4. false면 실제 축척으로 그린다
collapseDepth	number	—	첫 렌더에서 이 깊이보다 깊은 스팬을 접는다
selectedId	string	—	선택된 스팬 id
onSelect	(id: string) => void	—	스팬 선택
onHover	(id: string \| null) => void	—	행 호버 — 상세 패널 동기화용
kindColors	Record<string, string>	—	kind별 색. 지정하지 않으면 kindOrder 순서의 범주 슬롯
kindOrder	readonly string[]	—	kind가 색 슬롯을 받는 순서. 기본은 이름순 정렬 — 먼저 등장한 kind가 1번을 받으면 트레이스마다 색이 바뀐다
showLegend	boolean	—	kind 범례. 기본은 kind가 둘 이상일 때만 표시
locale	string	—	기본 소요 시간 포맷(Intl unit) 로캘
loading	boolean	false	새 트레이스를 기다리는 동안 현재 그림을 흐리게 유지
rowHeight	number	28	행 최소 높이
labelWidth	string	"minmax(8rem, 14rem)"	이름 열 grid track. 좁은 컨테이너에서는 줄여 축을 확보한다
maxRows	number	500	렌더할 행 상한
valueFormatter	(durationMs: number) => string	—	소요 시간 표기. 기본은 Intl 단위 포맷(380ms · 2.90s · 2m 5s)
labels	TraceWaterfallLabels	—	문구 재정의: 빈 상태, 유휴 구간, 펼침/접힘, 잘린 행(truncated), 실패 표식, 축 이름, 범례 이름
emptyState	ReactNode	—	스팬이 없을 때 표시할 내용
className	string	—	추가 CSS 클래스
aria-label	string	—	축 설명

View test results

테스트 커버리지

2026년 7월 9일

생성된 테스트 결과를 찾지 못했습니다.

TraceWaterfall 항목이 문서 메타에 연결되어 있지만 현재 생성 파일에는 없습니다.

테스트를 추가한 뒤 `bun run generate:test-results`를 실행하거나 `testDescribe` 매핑을 다시 확인하세요.

키보드 동작

키	동작
ArrowUp / ArrowDown	이전/다음 보이는 행으로 이동
ArrowLeft / ArrowRight	접기·부모 이동 / 펼치기·자식 이동
Home / End	첫/마지막 보이는 행으로 이동
Enter / Space	스팬 선택 (disabled 행 제외)

Related components

PathFlowChart

Charts

Explore staged user paths with transition ribbons, session starts and exits, grid or proportional Sankey layouts, and linked hover highlighting.

TimeSeriesChart

Charts

Explore time series with fixed query ranges, automatic ticks, incomplete buckets, drag zoom, annotations, thresholds, and comparison overlays.

TimeSeriesTooltip

Charts

Read full timestamps and time zones, sorted values, totals, comparison deltas, and incomplete-bucket warnings.

SmallMultiples

Charts

Compare breakdowns in small time-series panels with a shared y-axis, synchronized crosshairs, top-value ordering, and a collapsed long tail.

VennDiagram

Charts

Compare two or three sets with area-scaled SVG circles, interactive exclusive regions, and an accessible table; three-set placement is approximate.

EventSparkline

Charts

Show an event label, value, change, and miniature trend chart together.

TraceWaterfall

Chart

Inspect nested trace spans on one timeline with collapsible branches, explicit failure markers, and compressed idle gaps that preserve reported durations.

Related docs

bun add @reopt-ai/opt-charts

Install and import

bash

bun add @reopt-ai/opt-charts

tsx

import { TraceWaterfall } from "@reopt-ai/opt-charts";

Live preview

Change the width and theme, then interact with the components.

100%

에이전트 턴 트레이스

↑/↓로 행 이동, ←/→로 접기·펼치기, Enter 또는 Space로 선택합니다. 접힌 시간축에서도 소요 시간은 실제 값입니다.

유휴 구간 접기

승인을 기다린 2분을 접지 않으면 380ms 도구 호출이 점이 된다

embedding
generation
tool
trace

배송 문의

4.20s

gpt-5

입력 1,850 · 출력 240 · $0.0054

2.90s

lookup_order

380ms

text-embedding-3-small

160ms

배송 문의

3.10s

claude-sonnet-4-5

입력 3,120 · 출력 480 · $0.0081

3.00s

claude-haiku-4-5

APICallError · 529

1.00s

선택: gpt-5

입력 1,850 · 출력 240 · $0.0054

상태: 정상

좁은 패널과 빈 트레이스

embedding
generation
tool
trace

배송 문의

4.20s

gpt-5

입력 1,850 · 출력 240 · $0.0054

2.90s

lookup_order

380ms

text-embedding-3-small

160ms

배송 문의

3.10s

claude-sonnet-4-5

입력 3,120 · 출력 480 · $0.0081

3.00s

claude-haiku-4-5

APICallError · 529

1.00s

아직 수집된 스팬이 없습니다.

Usage guidance

Anatomy

Axis with folded idle intervals → span rows with indentation, collapse toggles, and names → duration bars with hatched idle intervals → elapsed time

Best practices

Use when spans in a trace need to be read by both chronology and parent-child relationships. Supply startMs/endMs as absolute epoch milliseconds; the component sets the axis.
Use kind to distinguish generation, tool, and embedding spans with automatic colors. Override specific colors with kindColors.
Share selection with a details panel through onSelect and selectedId. Clicking either the name or the bar selects the same span.
For more than a few hundred spans, limit rows with maxRows and provide a link to a list page.

Usage to avoid

Use GanttChart for schedules and roadmaps.
Disabling folding can reduce short calls to tiny dots when a trace contains long idle intervals. Disable it only when a true time scale is required.

Usage examples

Agent turn trace

TraceWaterfall

Prop	Type	Default	Description
spansRequired	TraceSpan[]	—	{ id, parentId?, name, startMs, endMs?, durationMs?, kind?, status?, detail?, disabled? } 목록. id는 고유해야 하며 시간은 절대 epoch ms. endMs가 없으면 durationMs를 사용하고 둘 다 없으면 순간 이벤트로 표시
folding	TraceWaterfallFolding \| false	—	{ ratio?: 0..1, ms?: number, markerWidth?: 0..1, maxTotal?: 0..1 }. 기본값은 각각 0.2, 10000, 0.08, 0.4. false면 실제 축척으로 그린다
collapseDepth	number	—	첫 렌더에서 이 깊이보다 깊은 스팬을 접는다
selectedId	string	—	선택된 스팬 id
onSelect	(id: string) => void	—	스팬 선택
onHover	(id: string \| null) => void	—	행 호버 — 상세 패널 동기화용
kindColors	Record<string, string>	—	kind별 색. 지정하지 않으면 kindOrder 순서의 범주 슬롯
kindOrder	readonly string[]	—	kind가 색 슬롯을 받는 순서. 기본은 이름순 정렬 — 먼저 등장한 kind가 1번을 받으면 트레이스마다 색이 바뀐다
showLegend	boolean	—	kind 범례. 기본은 kind가 둘 이상일 때만 표시
locale	string	—	기본 소요 시간 포맷(Intl unit) 로캘
loading	boolean	false	새 트레이스를 기다리는 동안 현재 그림을 흐리게 유지
rowHeight	number	28	행 최소 높이
labelWidth	string	"minmax(8rem, 14rem)"	이름 열 grid track. 좁은 컨테이너에서는 줄여 축을 확보한다
maxRows	number	500	렌더할 행 상한
valueFormatter	(durationMs: number) => string	—	소요 시간 표기. 기본은 Intl 단위 포맷(380ms · 2.90s · 2m 5s)
labels	TraceWaterfallLabels	—	문구 재정의: 빈 상태, 유휴 구간, 펼침/접힘, 잘린 행(truncated), 실패 표식, 축 이름, 범례 이름
emptyState	ReactNode	—	스팬이 없을 때 표시할 내용
className	string	—	추가 CSS 클래스
aria-label	string	—	축 설명

View test results

테스트 커버리지

2026년 7월 9일

생성된 테스트 결과를 찾지 못했습니다.

TraceWaterfall 항목이 문서 메타에 연결되어 있지만 현재 생성 파일에는 없습니다.

테스트를 추가한 뒤 `bun run generate:test-results`를 실행하거나 `testDescribe` 매핑을 다시 확인하세요.

키보드 동작

키	동작
ArrowUp / ArrowDown	이전/다음 보이는 행으로 이동
ArrowLeft / ArrowRight	접기·부모 이동 / 펼치기·자식 이동
Home / End	첫/마지막 보이는 행으로 이동
Enter / Space	스팬 선택 (disabled 행 제외)