Trace Waterfall
An agent run as a tree of spans on a time axis: agents, model calls and tool calls as tinted bars that grow while the run goes, the run's totals on top, finished branches folded into marks, and every span's details one click away.
oxyn add trace-waterfallTrace
Put the spring sale banner liveLive- Duration
- 0ms
- Cost
- $0.00
- Tokens
- 0
- Model calls
- 0
- Tool calls
- 0
- Errors
- 0
rsx! {
TraceWaterfall {
trace: Some(run.trace()),
at: Some(run.elapsed_ms()),
now: clock.now(),
}
}Rendered from Rust at build time · goes live when visible
When to use
- Show where an agent run spent its time and money: every agent, model call and tool call as a bar on one time axis, nested under whoever called it, live while the run goes and inspectable after.
When not to use
- An agent asks before it acts: use Approval Card instead.
- Several open requests in one card: use Approval pager instead.
- An agent's question in its own card above the composer: use Decision Card instead.
Installation
Trace Waterfall is free and MIT. The oxyn CLI copies its code, and the components it needs, into src/oxyn/ of your Dioxus or GPUI project, so it is yours to change.
cargo install --git https://github.com/ismailqureshi72/Oxyn oxyn-cli
oxyn init
oxyn add trace-waterfalluse crate::oxyn::{TraceWaterfall, STATUS_INDICATOR_CSS};Rather depend on the crate? cargo add oxyn-dioxus oxyn-core --git https://github.com/ismailqureshi72/Oxyn, then use oxyn_dioxus::{TraceWaterfall, STATUS_INDICATOR_CSS};
Usage
rsx! {
TraceWaterfall {
trace: Some(run.trace()),
at: Some(run.elapsed_ms()),
now: clock.now(),
}
}Examples
Live
The run replays and loops: spans slide in and grow with a sheen, the totals climb, the axis glides to the next round range, then the pill turns Done.
Trace
Put the spring sale banner liveLive- Duration
- 0ms
- Cost
- $0.00
- Tokens
- 0
- Model calls
- 0
- Tool calls
- 0
- Errors
- 0
Code
rsx! {
TraceWaterfall {
trace: Some(run.trace()),
at: Some(run.elapsed_ms()),
now: clock.now(),
}
}Early
Fourteen seconds in: the plan done, the researcher reading pages on a 15 s axis.
Trace
Put the spring sale banner liveLive- Duration
- 14.0s
- Cost
- $0.12
- Tokens
- 3.9k
- Model calls
- 1
- Tool calls
- 2
- Errors
- 0
Code
rsx! {
TraceWaterfall {
trace: Some(run.trace()),
at: Some(run.elapsed_ms()),
now: clock.now(),
}
}Mid
Mid-run: writer and coder side by side, a failed test run in red and the error count up.
Trace
Put the spring sale banner liveLive- Duration
- 38.0s
- Cost
- $0.51
- Tokens
- 25.5k
- Model calls
- 5
- Tool calls
- 3
- Errors
- 0
Code
rsx! {
TraceWaterfall {
trace: Some(run.trace()),
at: Some(run.elapsed_ms()),
now: clock.now(),
}
}Folded
Finished branches folded: their calls shrink to marks on the parent bar with a +n count.
Trace
Put the spring sale banner liveLive- Duration
- 38.0s
- Cost
- $0.51
- Tokens
- 25.5k
- Model calls
- 5
- Tool calls
- 3
- Errors
- 0
Code
rsx! {
TraceWaterfall {
trace: Some(run.trace()),
at: Some(run.elapsed_ms()),
now: clock.now(),
}
}Done
Finished: every span ended, the slowest call marked, the pill Done.
Trace
Put the spring sale banner liveDone- Duration
- 52.3s
- Cost
- $0.68
- Tokens
- 33.0k
- Model calls
- 7
- Tool calls
- 4
- Errors
- 1
Code
rsx! {
TraceWaterfall {
trace: Some(run.trace()),
at: Some(run.elapsed_ms()),
now: clock.now(),
}
}Details
A model call opened: duration, start, cost, tokens in and out, and what went in and came out.
Trace
Put the spring sale banner liveDone- Duration
- 52.3s
- Cost
- $0.68
- Tokens
- 33.0k
- Model calls
- 7
- Tool calls
- 4
- Errors
- 1
- Duration
- 8.6s
- Started
- +24.6s
- Cost
- $0.29
- Tokens in
- 8.8k
- Tokens out
- 2.3k
Banner.tsx and the copy.
A dismissible banner with a countdown.
Code
rsx! {
TraceWaterfall {
trace: Some(run.trace()),
at: Some(run.elapsed_ms()),
now: clock.now(),
}
}Failed
The failed tool call opened: a red status and the error text.
Trace
Put the spring sale banner liveDone- Duration
- 52.3s
- Cost
- $0.68
- Tokens
- 33.0k
- Model calls
- 7
- Tool calls
- 4
- Errors
- 1
- Duration
- 7.5s
- Started
- +33.5s
- Cost
- $0.00
npm test -- banner
3 of 11 banner tests failed: the end date is read in UTC, so the sale closes a day early for viewers in the west.
Code
rsx! {
TraceWaterfall {
trace: Some(run.trace()),
at: Some(run.elapsed_ms()),
now: clock.now(),
}
}Narrow
Under 560 px each row puts its bar under the name and the totals wrap to three columns.
Trace
Put the spring sale banner liveDone- Duration
- 52.3s
- Cost
- $0.68
- Tokens
- 33.0k
- Model calls
- 7
- Tool calls
- 4
- Errors
- 1
Code
rsx! {
TraceWaterfall {
trace: Some(run.trace()),
at: Some(run.elapsed_ms()),
now: clock.now(),
}
}Classic
Classic style: a grey header band, sentence-case labels, roomier rows.
Trace
Put the spring sale banner liveLive- Duration
- 38.0s
- Cost
- $0.51
- Tokens
- 25.5k
- Model calls
- 5
- Tool calls
- 3
- Errors
- 0
Code
rsx! {
TraceWaterfall {
trace: Some(run.trace()),
at: Some(run.elapsed_ms()),
now: clock.now(),
}
}API reference
TraceWaterfall
| Prop | Type | Default | Description |
|---|---|---|---|
trace | Option<TwSpan> | Default::default() | The trace (the demo's when `None`). |
at | Option<u32> | Default::default() | Ms into the run; `None` replays the demo (looping). |
task | String | "Put the spring sale banner live" | The task line. |
title | String | "Trace" | Heading. |
folded | Vec<String> | Default::default() | Branches folded from the start (ids). |
open | Option<String> | Default::default() | A span whose details are open from the start (id). |
nowrequired | ClockMs | — | The clock (drives the replay). |
style | String | Default::default() | `clean`, `classic`, or empty to follow `data-cstyle`. |
on_open | EventHandler<Option<String>> | — | A span's details were opened (id) or closed. |
Read from the Rust signature and doc comments.
Keyboard interactions
| Key | Action |
|---|---|
| Tab | The span tree is one stop |
| UporDownorHomeorEnd | Move through the spans |
| RightorLeft | Unfold / fold a branch |
| EnterorSpace | Opens the span's details |
| Escape | Closes the details |
Accessibility
- The spans are a tree (treeitems with levels and expanded state) with one tab stop and an active descendant.
- The Live / Done pill is a status region; a failed span carries a warning icon and the word Failed in its details, not only red.
- Reduced motion stops the sheen, the shimmer on the totals and the glides.
Responsive behaviour
- Wide: the span names on the left, the time axis on the right.
- Under 560 px each row stacks its bar under the name and the totals wrap to three columns; under 360 px the muted details drop.
Edge cases (spec)
Under 560 px the totals wrap to three columns, the axis hides and each row puts its bar under the name; under 360 px the muted details and labels drop.
Notes for AI
- Import
TraceWaterfallfromoxyn_dioxusand includeSTATUS_INDICATOR_CSSplus the token stylesheet once. - A GPUI version exists:
TraceWaterfallElinoxyn_gpui. - Props to set first:
now. - It reads a clock (
now) for live timers; pass one clock for the whole page rather than one per component. - Keep its states and timings as they ship; restyle it through the CSS variables rather than by hand.