TraceWaterfall

visual

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

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

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

테스트 커버리지

2026년 7월 9일

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

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

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

TraceWaterfall Props

Prop	타입	기본값	설명
`spans`*	`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`	—	축 설명

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";

키보드 동작

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

TraceWaterfall

visual

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

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

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

테스트 커버리지

2026년 7월 9일

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

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

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

TraceWaterfall Props

Prop	타입	기본값	설명
`spans`*	`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`	—	축 설명

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";

키보드 동작

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