TraceWaterfall
visual트레이스의 스팬을 하나의 시간축에 놓는 워터폴. 부모-자식 관계로 들여쓰고 접을 수 있으며, 실패한 스팬은 색이 아니라 표식으로 알린다. 아무 스팬도 덮지 않는 유휴 구간은 접어서 짧은 호출이 점으로 뭉개지지 않게 한다 — 접히는 것은 위치뿐이고 표시되는 소요 시간은 실제 값이다.
100%
에이전트 턴 트레이스
유휴 구간 접기
승인을 기다린 2분을 접지 않으면 380ms 도구 호출이 점이 된다
4.20s
입력 1,850 · 출력 240 · $0.0054
2.90s3.10s
입력 3,120 · 출력 480 · $0.0081
APICallError · 529
선택: gen-0
테스트 커버리지
2026년 7월 9일생성된 테스트 결과를 찾지 못했습니다.
TraceWaterfall 항목이 문서 메타에 연결되어 있지만 현재 생성 파일에는 없습니다.
테스트를 추가한 뒤 `bun run generate:test-results`를 실행하거나 `testDescribe` 매핑을 다시 확인하세요.
TraceWaterfall Props
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
spans* | TraceSpan[] | — | 스팬 목록. startMs/endMs는 절대 epoch ms |
folding | TraceWaterfallFolding | false | — | 유휴 구간 접기 기준. false면 실제 축척으로 그린다 |
collapseDepth | number | — | 첫 렌더에서 이 깊이보다 깊은 스팬을 접는다 |
selectedId | string | — | 선택된 스팬 id |
onSelect | (id: string) => void | — | 스팬 선택 |
onHover | (id: string | null) => void | — | 행 호버 — 상세 패널 동기화용 |
kindColors | Record<string, string> | — | kind별 색. 지정하지 않으면 팔레트 순서 |
rowHeight | number | 28 | 행 최소 높이 |
labelWidth | string | "minmax(8rem, 14rem)" | 이름 열 grid track. 좁은 컨테이너에서는 줄여 축을 확보한다 |
maxRows | number | 500 | 렌더할 행 상한 |
valueFormatter | (durationMs: number) => string | — | 소요 시간 표기 |
labels | TraceWaterfallLabels | — | 문구 재정의 |
emptyState | ReactNode | — | 스팬이 없을 때 표시할 내용 |
className | string | — | 추가 CSS 클래스 |
aria-label | string | — | 축 설명 |
Design contract
Usage
- 한 트레이스의 스팬을 시간 순서와 부모-자식 관계로 함께 읽어야 할 때 씁니다. startMs/endMs는 절대 epoch ms로 넘기세요 — 컴포넌트가 축을 잡습니다.
- kind로 생성·도구·임베딩을 구분하면 색이 자동으로 갈립니다. 특정 색이 필요하면 kindColors로 지정하세요.
- onSelect와 selectedId로 상세 패널과 선택을 공유하세요. 이름과 막대 어느 쪽을 눌러도 같은 스팬이 선택됩니다.
- 스팬이 수백 개를 넘으면 maxRows로 자르고 목록 페이지로 유도하세요.
- Avoid: 일정·로드맵에는 쓰지 마세요. 그건 GanttChart입니다.
- Avoid: folding을 끄면 긴 유휴 구간이 있는 트레이스에서 짧은 호출이 점으로 사라집니다. 실제 축척이 꼭 필요할 때만 끄세요.
Import
tsx
import { TraceWaterfall } from "@reopt-ai/opt-ui";