hyperdx/.changeset/optimize-trace-waterfall.md at 3c057720efb92496e68c2f2568544151b8fdeefc

mirror of https://github.com/hyperdxio/hyperdx synced 2026-04-21 13:37:15 +00:00

[HDX-3963] Optimize event detail and trace waterfall queries (#2104 )

## Summary

Optimizes the queries powering the event details panel and trace waterfall chart in the TUI, and improves the trace waterfall UX.

Fixes HDX-3963
Linear: https://linear.app/clickhouse/issue/HDX-3963

### Query optimizations

**Full row fetch (`SELECT *`)** — Removed the 1-year `dateRange` from `buildFullRowQuery`. The WHERE clause already uniquely identifies the row, so ClickHouse can use the filter directly without scanning time partitions. Matches the web frontend's `useRowData` pattern in `DBRowDataPanel.tsx`.

**Trace waterfall queries** — Replaced raw SQL builders (`buildTraceSpansSql`/`buildTraceLogsSql`) with `renderChartConfig`-based async builders. This enables:
- Time partition pruning via a tight ±1h `dateRange` derived from the event timestamp
- Materialized field optimization
- Query parameterization

**Trace span detail fetch** — Replaced raw SQL `SELECT * FROM ... WHERE ... LIMIT 1` with `renderChartConfig` via `buildTraceRowDetailConfig`, omitting `dateRange`/`timestampValueExpression` so ClickHouse uses the WHERE clause directly.

**Shared logic** — Extracted all trace config construction into `packages/cli/src/shared/traceConfig.ts`.

### UX improvements

**Trace Event Details → dedicated page** — Previously Event Details was rendered inline below the waterfall, consuming screen space. Now:
- Waterfall view gets the full terminal height
- Press `l`/`Enter` to drill into a span's full Event Details
- Press `h`/`Esc` to return to the waterfall
- `Ctrl+D/U` scrolls the detail view using full terminal height

**Trace waterfall scrolling** — Previously the waterfall truncated at `maxRows` with no way to see remaining spans. Now `j`/`k` scrolls the viewport when the cursor reaches the edge, with a scroll position indicator showing spans above/below.

### Files changed

| File | Change |
|---|---|
| `packages/cli/src/shared/traceConfig.ts` | NEW — shared trace config builders |
| `packages/cli/src/api/eventQuery.ts` | Replace raw SQL with `renderChartConfig`; remove date range from full row fetch |
| `packages/cli/src/components/TraceWaterfall/TraceWaterfall.tsx` | Split into waterfall + detail views; add scroll support |
| `packages/cli/src/components/TraceWaterfall/useTraceData.ts` | Use async builders + parameterized queries |
| `packages/cli/src/components/TraceWaterfall/types.ts` | Add `metadata`, `eventTimestamp`, `detailExpanded` props |
| `packages/cli/src/components/EventViewer/useKeybindings.ts` | Add `l`/`h` keybindings for trace detail navigation |
| `packages/cli/src/components/EventViewer/DetailPanel.tsx` | Thread `metadata`, `eventTimestamp`, `traceDetailExpanded` |
| `packages/cli/src/components/EventViewer/EventViewer.tsx` | Add `traceDetailExpanded` state; pass new props |

2026-04-13 21:39:41 +00:00

128 B

Raw Blame History

@hyperdx/cli
patch

Optimize event detail and trace waterfall queries; add trace detail page and waterfall scrolling

128 B Raw Blame History

128 B

Raw Blame History