diff --git a/.changeset/trace-search-duration-heatmap.md b/.changeset/trace-search-duration-heatmap.md new file mode 100644 index 000000000..0d3278cc0 --- /dev/null +++ b/.changeset/trace-search-duration-heatmap.md @@ -0,0 +1,5 @@ +--- +'@hyperdx/app': minor +--- + +Add a RED/Heatmap switch to the trace search results view. Heatmap shows the duration distribution over time as the same tile the dashboard renders, and the choice is kept in the URL so a reload or a shared link reopens the same view. diff --git a/packages/app/src/DBSearchPage.tsx b/packages/app/src/DBSearchPage.tsx index 9246506a1..c754eb2e3 100644 --- a/packages/app/src/DBSearchPage.tsx +++ b/packages/app/src/DBSearchPage.tsx @@ -60,6 +60,7 @@ import { Group, Modal, Paper, + SegmentedControl, Select, Stack, Text, @@ -155,7 +156,11 @@ import DBSqlRowTableWithSideBar from './components/DBSqlRowTableWithSidebar'; import PatternTable from './components/PatternTable'; import { DBSearchHeatmapChart } from './components/Search/DBSearchHeatmapChart'; import DirectTraceSidePanel from './components/Search/DirectTraceSidePanel'; -import { TraceRedMetricsChart } from './components/Search/TraceRedMetricsChart'; +import { + TRACE_CHART_MODES, + TraceRedMetricsChart, +} from './components/Search/TraceRedMetricsChart'; +import { useHeatmapLiveTailGuard } from './components/Search/useHeatmapLiveTailGuard'; import SourceSchemaPreview, { isSourceSchemaPreviewEnabled, } from './components/SourceSchemaPreview'; @@ -1118,6 +1123,14 @@ function DBSearchPageContent() { ]).withDefault('results'), ); + // RED metrics vs heatmap for the trace results chart area. URL state (like + // the other view toggles on this page) so a reload or shared link keeps the + // chosen view; the switch lives inline in the search stats row. + const [traceChartMode, setTraceChartMode] = useQueryState( + 'traceChartMode', + parseAsStringEnum([...TRACE_CHART_MODES]).withDefault('red'), + ); + // URL-only, not saved with the search: null uses the source default. const [groupByParam, setGroupByParam] = useQueryState( 'groupBy', @@ -1453,6 +1466,13 @@ function DBSearchPageContent() { // Same, for the histogram group by. Also set when a saved search switches the // source, since the group by isn't part of the saved search. const pendingGroupByReconcileRef = useRef(null); + // Same, for the trace RED/Heatmap choice, which was made for the previous + // source: a source the user picks opens in the default RED view, so coming + // back to a trace source doesn't silently reopen the heatmap (and turn live + // tail off again). The reset waits until the URL points at the new source, + // so it lands on the new history entry and leaves the previous one intact; + // Back/Forward never set this, so they keep the mode the URL restores. + const pendingTraceChartModeResetRef = useRef(null); const watchedSourceObj = useMemo( () => inputSourceObjs?.find(s => s.id === watchedSource), @@ -1515,6 +1535,7 @@ function DBSearchPageContent() { // a freshly loaded page pushes its defaults into the search config. if (!isCatchingUpToConfig) { pendingGroupByReconcileRef.current = watchedSource ?? null; + pendingTraceChartModeResetRef.current = watchedSource ?? null; // If the user isn't in a saved search (or the source is different from the saved search source), reset fields if (savedSearchId == null || savedSearch?.source !== watchedSource) { setValue('select', ''); @@ -1547,6 +1568,18 @@ function DBSearchPageContent() { setSearchedConfig, ]); + useEffect(() => { + if ( + pendingTraceChartModeResetRef.current != null && + pendingTraceChartModeResetRef.current === searchedSource?.id + ) { + pendingTraceChartModeResetRef.current = null; + // Cleared rather than set to 'red': nuqs 1.x writes an explicit default + // into the URL. + setTraceChartMode(null); + } + }, [searchedSource?.id, setTraceChartMode]); + const retainCompatibleFiltersAndGroupBy = useStableCallback( (columns: ColumnMeta[]) => { const allowed = new Set(columns.map(c => c.name)); @@ -2016,10 +2049,10 @@ function DBSearchPageContent() { const aliasWith = useMemo(() => aliasMapToWithClauses(aliasMap), [aliasMap]); - // The trace results chart shows RED metrics only for a trace source that - // exposes a duration column; otherwise the single histogram stays. Derived - // once, as the narrowed source or null, so the callers can't drift apart on - // which one renders. + // The trace results chart shows RED metrics (and a heatmap) only for a trace + // source that exposes a duration column; otherwise the single histogram + // stays. Derived once, as the narrowed source or null, so the callers can't + // drift apart on which one renders. const traceRedMetricsSource = searchedSource != null && isTraceSource(searchedSource) && @@ -2086,6 +2119,47 @@ function DBSearchPageContent() { [isCustomGroupBy, histogramTimeChartConfig, searchedSource], ); + // The RED/Heatmap chart area renders only where it fits: a trace source with + // a duration column, on a non-compact viewport (three side-by-side tiles + // would be unreadable on a phone), without a custom group-by (the RED tiles + // have fixed grouping, so a custom group-by falls back to the histogram, + // which honors it). Derived once, as the narrowed source or null, so the + // chart branch, the stats-row RED/Heatmap switch and the live-tail pin can't + // drift apart on which one renders. + const traceChartsSource = + traceRedMetricsSource != null && !isCompact && !isCustomGroupBy + ? traceRedMetricsSource + : null; + + // Base config for the trace heatmap tile, mirroring the delta-mode heatmap: + // the search's chart config over the searched range, carrying the source's + // select-alias definitions. Memoized so the tile's query stays stable across + // re-renders. + const traceHeatmapChartConfig = useMemo( + () => + chartConfig == null + ? undefined + : ({ + ...chartConfig, + dateRange: searchedTimeRange, + with: aliasWith, + } satisfies BuilderChartConfigWithDateRange), + [chartConfig, searchedTimeRange, aliasWith], + ); + + // Live tail stays off while the heatmap is the visible chart, the way delta + // and pattern modes keep it off: the guard below turns it off, and the + // TimePicker's Live option and the Resume Live Tail button are hidden. + // Results mode defaults to live, so this view has to opt out for itself. + // Only while the heatmap is actually rendered, so a stale + // ?traceChartMode=heatmap on a source that shows the histogram can't disable + // live tail. + const isHeatmapChartVisible = + analysisMode === 'results' && + traceChartsSource != null && + traceChartMode === 'heatmap'; + useHeatmapLiveTailGuard({ isHeatmapChartVisible, isLive, setIsLive }); + const histogramGroupBySelect = ( + {traceChartsSource != null && ( + + setTraceChartMode( + TRACE_CHART_MODES.find( + mode => mode === v, + ) ?? 'red', + ) + } + data={[ + { label: 'RED', value: 'red' }, + { label: 'Heatmap', value: 'heatmap' }, + ]} + /> + )} {shouldShowLiveModeHint && - denoiseResults != true && ( + denoiseResults != true && + !isHeatmapChartVisible && ( @@ -2901,25 +2993,22 @@ function DBSearchPageContent() { {!hasQueryError && - // The three side-by-side RED tiles need room, so on a - // compact (narrow/mobile) viewport fall back to the - // single histogram. The RED tiles also have fixed - // grouping (Throughput by status, Errors by status, - // Duration ungrouped), so when the user picks a custom - // group-by fall back to the histogram, which honors it. - (traceRedMetricsSource != null && - !isCompact && - !isCustomGroupBy ? ( + // RED/Heatmap where it fits, else the histogram; see + // traceChartsSource for when each one renders. + (traceChartsSource != null && + traceHeatmapChartConfig != null ? ( + toHeatmapQuery({ + ...heatmapChartConfig, + select: [ + { + valueExpression: durationMsExpression, + countExpression: 'count()', + heatmapScaleType: 'log', + }, + ], + numberFormat: HEATMAP_DURATION_NUMBER_FORMAT, + }), + [heatmapChartConfig, durationMsExpression], + ); + const errorsModeControl = ( + + + ); + } + return ( diff --git a/packages/app/src/components/Search/__tests__/useHeatmapLiveTailGuard.test.ts b/packages/app/src/components/Search/__tests__/useHeatmapLiveTailGuard.test.ts new file mode 100644 index 000000000..8306bc7f1 --- /dev/null +++ b/packages/app/src/components/Search/__tests__/useHeatmapLiveTailGuard.test.ts @@ -0,0 +1,56 @@ +import { renderHook } from '@testing-library/react'; + +import { useHeatmapLiveTailGuard } from '@/components/Search/useHeatmapLiveTailGuard'; + +type Props = { + isHeatmapChartVisible: boolean; + isLive: boolean; +}; + +function renderGuard(initialProps: Props) { + // A stable setter, like the nuqs one on the search page, so only the props + // under test retrigger the effect. + const setIsLive = jest.fn(); + const hook = renderHook( + (props: Props) => useHeatmapLiveTailGuard({ ...props, setIsLive }), + { initialProps }, + ); + return { ...hook, setIsLive }; +} + +describe('useHeatmapLiveTailGuard', () => { + it('turns live tail off when the heatmap becomes visible', () => { + const { rerender, setIsLive } = renderGuard({ + isHeatmapChartVisible: false, + isLive: true, + }); + expect(setIsLive).not.toHaveBeenCalled(); + + rerender({ isHeatmapChartVisible: true, isLive: true }); + expect(setIsLive).toHaveBeenCalledTimes(1); + expect(setIsLive).toHaveBeenCalledWith(false); + }); + + it('turns live tail off again when it is resumed under the heatmap', () => { + const { rerender, setIsLive } = renderGuard({ + isHeatmapChartVisible: true, + isLive: false, + }); + expect(setIsLive).not.toHaveBeenCalled(); + + rerender({ isHeatmapChartVisible: true, isLive: true }); + expect(setIsLive).toHaveBeenCalledTimes(1); + expect(setIsLive).toHaveBeenCalledWith(false); + }); + + it('leaves live tail alone while the RED view is showing', () => { + const { rerender, setIsLive } = renderGuard({ + isHeatmapChartVisible: false, + isLive: true, + }); + rerender({ isHeatmapChartVisible: false, isLive: false }); + rerender({ isHeatmapChartVisible: false, isLive: true }); + + expect(setIsLive).not.toHaveBeenCalled(); + }); +}); diff --git a/packages/app/src/components/Search/useHeatmapLiveTailGuard.ts b/packages/app/src/components/Search/useHeatmapLiveTailGuard.ts new file mode 100644 index 000000000..db2b4b42e --- /dev/null +++ b/packages/app/src/components/Search/useHeatmapLiveTailGuard.ts @@ -0,0 +1,26 @@ +import { useEffect } from 'react'; + +/** + * Keeps live tail off while the trace heatmap is the visible chart, the way + * delta and pattern modes keep it off. A live tick moves the absolute time + * range, and the heatmap keys its uPlot instance on the chart config, so every + * refresh would tear the chart down and rebuild it with a recomputed y-axis + * instead of updating in place. `isLive` is part of the check, not just the + * visibility, so live tail turned back on while the heatmap is showing + * (through any control) is switched off again. + */ +export function useHeatmapLiveTailGuard({ + isHeatmapChartVisible, + isLive, + setIsLive, +}: { + isHeatmapChartVisible: boolean; + isLive: boolean; + setIsLive: (isLive: boolean) => unknown; +}) { + useEffect(() => { + if (isHeatmapChartVisible && isLive) { + setIsLive(false); + } + }, [isHeatmapChartVisible, isLive, setIsLive]); +}