diff --git a/.changeset/trace-search-duration-heatmap.md b/.changeset/trace-search-duration-heatmap.md new file mode 100644 index 0000000000..0d3278cc02 --- /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 841e88392c..7e40d96065 100644 --- a/packages/app/src/DBSearchPage.tsx +++ b/packages/app/src/DBSearchPage.tsx @@ -61,6 +61,7 @@ import { Group, Modal, Paper, + SegmentedControl, Select, Stack, Text, @@ -163,7 +164,12 @@ 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 { useTraceChartModeReset } from './components/Search/useTraceChartModeReset'; import SourceSchemaPreview, { isSourceSchemaPreviewEnabled, } from './components/SourceSchemaPreview'; @@ -1126,6 +1132,13 @@ function DBSearchPageContent() { ]).withDefault('results'), ); + // RED vs heatmap for the trace results chart. URL state, like the page's + // other view toggles, so a reload or shared link keeps the view. + 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', @@ -1461,6 +1474,12 @@ 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 (see useTraceChartModeReset). + const { arm: armTraceChartModeReset, disarm: disarmTraceChartModeReset } = + useTraceChartModeReset({ + searchedSourceId: searchedSource?.id, + setTraceChartMode, + }); const watchedSourceObj = useMemo( () => inputSourceObjs?.find(s => s.id === watchedSource), @@ -1527,6 +1546,11 @@ function DBSearchPageContent() { const isCatchingUpToConfig = !!watchedSource && watchedSource === searchedSource?.id; + // Re-selecting the searched source undoes a pick whose search hasn't run. + if (isCatchingUpToConfig) { + disarmTraceChartModeReset(); + } + if (isCatchingUpToConfig && savedSearchId == null) { prevSourceRef.current = watchedSource; if (rawSearchedConfig.source !== watchedSource) { @@ -1552,6 +1576,7 @@ function DBSearchPageContent() { // a freshly loaded page pushes its defaults into the search config. if (!isCatchingUpToConfig) { pendingGroupByReconcileRef.current = watchedSource ?? null; + armTraceChartModeReset(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', ''); @@ -1582,6 +1607,8 @@ function DBSearchPageContent() { searchedSource?.id, rawSearchedConfig.source, setSearchedConfig, + armTraceChartModeReset, + disarmTraceChartModeReset, ]); const retainCompatibleFiltersAndGroupBy = useStableCallback( @@ -2123,6 +2150,43 @@ function DBSearchPageContent() { [isCustomGroupBy, histogramTimeChartConfig, searchedSource], ); + // The RED/Heatmap area renders only where it fits: not on a compact viewport, + // and not with a custom group-by, which the RED tiles' fixed grouping can't + // honor (the histogram can). The chart branch, the switch and the live-tail + // guard all read this, so they agree on which chart shows. + const traceChartsSource = + traceRedMetricsSource != null && !isCompact && !isCustomGroupBy + ? traceRedMetricsSource + : null; + + // Base config for the trace heatmap, like the delta-view heatmap's. The + // table's sort is dropped: the chart keys its uPlot instance on the config, + // so sorting a column would otherwise rebuild it. + const traceHeatmapChartConfig = useMemo( + () => + chartConfig == null + ? undefined + : ({ + ...chartConfig, + orderBy: undefined, + dateRange: searchedTimeRange, + with: aliasWith, + } satisfies BuilderChartConfigWithDateRange), + [chartConfig, searchedTimeRange, aliasWith], + ); + + // While the heatmap shows, live tail stays off as in delta and pattern modes: + // the guard turns it off and the Live option and Resume Live Tail are hidden. + // Uses the chart branch's conditions, so a stale ?traceChartMode=heatmap or a + // query error that hides the chart can't take live tail away. + const isHeatmapChartVisible = + analysisMode === 'results' && + traceChartsSource != null && + traceChartMode === 'heatmap' && + traceHeatmapChartConfig != null && + !hasQueryError; + useHeatmapLiveTailGuard({ isHeatmapChartVisible, isLive, setIsLive }); + const histogramGroupBySelect = ( - {histogramGroupBySelect} + {/* The heatmap doesn't group. */} + {isHeatmapChartVisible + ? null + : histogramGroupBySelect} + {traceChartsSource != null && ( + + setTraceChartMode( + TRACE_CHART_MODES.find( + mode => mode === v && mode !== 'red', + ) ?? null, + ) + } + data={[ + { label: 'RED', value: 'red' }, + { label: 'Heatmap', value: 'heatmap' }, + ]} + /> + )} {shouldShowLiveModeHint && - denoiseResults != true && ( + denoiseResults != true && + !isHeatmapChartVisible && ( @@ -2941,25 +3028,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__/TraceRedMetricsChart.test.tsx b/packages/app/src/components/Search/__tests__/TraceRedMetricsChart.test.tsx new file mode 100644 index 0000000000..a2b1a3a838 --- /dev/null +++ b/packages/app/src/components/Search/__tests__/TraceRedMetricsChart.test.tsx @@ -0,0 +1,145 @@ +import React from 'react'; +import { + BuilderChartConfigWithDateRange, + SourceKind, + TTraceSource, +} from '@hyperdx/common-utils/dist/types'; +import { screen } from '@testing-library/react'; + +import type DBHeatmapChartType from '@/components/DBHeatmapChart'; +import { HEATMAP_DURATION_NUMBER_FORMAT } from '@/components/DBHeatmapChart'; +import type { DBTimeChart as DBTimeChartType } from '@/components/DBTimeChart'; +import { TraceRedMetricsChart } from '@/components/Search/TraceRedMetricsChart'; + +type HeatmapProps = React.ComponentProps; +type TimeChartProps = React.ComponentProps; +const mockHeatmapProps: HeatmapProps[] = []; +const mockTimeChartProps: TimeChartProps[] = []; + +// Only the chart components are stubbed. The real query builder and number +// format stay, so the test checks the query the heatmap actually gets. +jest.mock('../../DBHeatmapChart', () => ({ + __esModule: true, + default: jest.fn((props: HeatmapProps) => { + mockHeatmapProps.push(props); + return
; + }), + toHeatmapQuery: jest.requireActual< + typeof import('../../DBHeatmapChart/heatmapQueries') + >('../../DBHeatmapChart/heatmapQueries').toHeatmapQuery, + HEATMAP_DURATION_NUMBER_FORMAT: jest.requireActual< + typeof import('../../DBHeatmapChart/heatmapAxis') + >('../../DBHeatmapChart/heatmapAxis').HEATMAP_DURATION_NUMBER_FORMAT, +})); + +jest.mock('../../DBTimeChart', () => ({ + DBTimeChart: jest.fn((props: TimeChartProps) => { + mockTimeChartProps.push(props); + return
; + }), +})); + +jest.mock('@/source', () => ({ + ...jest.requireActual('@/source'), + getDurationMsExpression: jest.fn(() => 'duration_ms_expr'), +})); + +const source: TTraceSource = { + id: 'trace-source', + kind: SourceKind.Trace, + name: 'Trace Source', + connection: 'conn', + from: { databaseName: 'otel', tableName: 'otel_traces' }, + timestampValueExpression: 'Timestamp', + defaultTableSelectExpression: 'Timestamp', + durationExpression: 'Duration', + durationPrecision: 3, + traceIdExpression: 'TraceId', + spanIdExpression: 'SpanId', + parentSpanIdExpression: 'ParentSpanId', + spanNameExpression: 'SpanName', + spanKindExpression: 'SpanKind', + statusCodeExpression: 'StatusCode', +}; + +const baseConfig: BuilderChartConfigWithDateRange = { + dateRange: [new Date(0), new Date(60_000)], + from: { databaseName: 'otel', tableName: 'otel_traces' }, + timestampValueExpression: 'Timestamp', + connection: 'conn', + select: '', + where: '', + whereLanguage: 'sql', +}; + +const histogramTimeChartConfig: BuilderChartConfigWithDateRange = { + ...baseConfig, + select: [{ aggFn: 'count', aggCondition: '', valueExpression: '' }], + groupBy: 'StatusCode', + granularity: 'auto', +}; + +function renderChart(mode: 'red' | 'heatmap') { + renderWithMantine( + , + ); +} + +function asDistribution(query: HeatmapProps['query']) { + if (query.mode !== 'distribution') { + throw new Error(`expected a distribution query, got ${query.mode}`); + } + return query; +} + +describe('TraceRedMetricsChart', () => { + beforeEach(() => { + jest.clearAllMocks(); + mockHeatmapProps.length = 0; + mockTimeChartProps.length = 0; + }); + + it('renders the duration heatmap, not the RED tiles, in heatmap mode', () => { + renderChart('heatmap'); + + expect(screen.getByTestId('db-heatmap-chart')).toBeInTheDocument(); + expect(screen.queryByTestId('db-time-chart')).not.toBeInTheDocument(); + + const props = mockHeatmapProps[mockHeatmapProps.length - 1]; + expect(props.enabled).toBe(true); + const query = asDistribution(props.query); + // The source's duration in ms, counted per bucket on a log scale, with the + // duration number format: the delta view's default duration heatmap. + expect(query.config.select).toEqual([ + { + aggFn: 'heatmap', + valueExpression: 'duration_ms_expr', + countExpression: 'count()', + }, + ]); + expect(query.scaleType).toBe('log'); + expect(query.config.numberFormat).toEqual(HEATMAP_DURATION_NUMBER_FORMAT); + expect(query.config.dateRange).toBe(baseConfig.dateRange); + }); + + it('renders the three RED tiles, not the heatmap, in RED mode', () => { + renderChart('red'); + + expect(screen.queryByTestId('db-heatmap-chart')).not.toBeInTheDocument(); + expect(new Set(mockTimeChartProps.map(p => p.title))).toEqual( + new Set(['Throughput', 'Errors', 'Duration']), + ); + // Only the Duration tile opts into its select items' pinned colors. + expect( + new Set( + mockTimeChartProps.filter(p => p.applySelectColors).map(p => p.title), + ), + ).toEqual(new Set(['Duration'])); + }); +}); 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 0000000000..8306bc7f18 --- /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/__tests__/useTraceChartModeReset.test.ts b/packages/app/src/components/Search/__tests__/useTraceChartModeReset.test.ts new file mode 100644 index 0000000000..1ed7097e21 --- /dev/null +++ b/packages/app/src/components/Search/__tests__/useTraceChartModeReset.test.ts @@ -0,0 +1,82 @@ +import { act, renderHook } from '@testing-library/react'; + +import { useTraceChartModeReset } from '@/components/Search/useTraceChartModeReset'; + +type Props = { searchedSourceId: string | undefined }; + +function renderReset(searchedSourceId: string | undefined) { + // A stable setter, like the nuqs one on the search page, so only the + // searched source retriggers the effect. + const setTraceChartMode = jest.fn(); + const hook = renderHook( + ({ searchedSourceId }: Props) => + useTraceChartModeReset({ searchedSourceId, setTraceChartMode }), + { initialProps: { searchedSourceId } }, + ); + return { ...hook, setTraceChartMode }; +} + +describe('useTraceChartModeReset', () => { + it('clears the mode once the searched source reaches the picked source', () => { + const { result, rerender, setTraceChartMode } = renderReset('traces'); + + act(() => result.current.arm('logs')); + // The pick alone doesn't reset: the URL still points at the old source. + rerender({ searchedSourceId: 'traces' }); + expect(setTraceChartMode).not.toHaveBeenCalled(); + + rerender({ searchedSourceId: 'logs' }); + expect(setTraceChartMode).toHaveBeenCalledTimes(1); + expect(setTraceChartMode).toHaveBeenCalledWith(null); + }); + + it('fires once per pick', () => { + const { result, rerender, setTraceChartMode } = renderReset('traces'); + + act(() => result.current.arm('logs')); + rerender({ searchedSourceId: 'logs' }); + rerender({ searchedSourceId: 'traces' }); + rerender({ searchedSourceId: 'logs' }); + + expect(setTraceChartMode).toHaveBeenCalledTimes(1); + }); + + // Back/Forward changes the searched source without a pick, so the mode the + // URL restores stays. + it('leaves source changes it was not armed for alone', () => { + const { rerender, setTraceChartMode } = renderReset('logs'); + + rerender({ searchedSourceId: 'traces' }); + rerender({ searchedSourceId: 'logs' }); + + expect(setTraceChartMode).not.toHaveBeenCalled(); + }); + + // Re-selecting the searched source before the search runs undoes the pick; + // a later navigation to the abandoned source must not trigger the reset. + it('drops an armed reset when the pick is undone', () => { + const { result, rerender, setTraceChartMode } = renderReset('traces'); + + act(() => { + result.current.arm('logs'); + result.current.disarm(); + }); + rerender({ searchedSourceId: 'logs' }); + + expect(setTraceChartMode).not.toHaveBeenCalled(); + }); + + it('follows the latest pick', () => { + const { result, rerender, setTraceChartMode } = renderReset('traces'); + + act(() => { + result.current.arm('logs'); + result.current.arm('sessions'); + }); + rerender({ searchedSourceId: 'logs' }); + expect(setTraceChartMode).not.toHaveBeenCalled(); + + rerender({ searchedSourceId: 'sessions' }); + expect(setTraceChartMode).toHaveBeenCalledTimes(1); + }); +}); diff --git a/packages/app/src/components/Search/useHeatmapLiveTailGuard.ts b/packages/app/src/components/Search/useHeatmapLiveTailGuard.ts new file mode 100644 index 0000000000..38ad38d0ad --- /dev/null +++ b/packages/app/src/components/Search/useHeatmapLiveTailGuard.ts @@ -0,0 +1,23 @@ +import { useEffect } from 'react'; + +/** + * Keeps live tail off while the trace heatmap shows: each tick moves the time + * range, and the heatmap keys its uPlot instance on the config, so it would + * rebuild on every refresh. Checking `isLive` too switches live tail off again + * if any control turns it back on under the heatmap. + */ +export function useHeatmapLiveTailGuard({ + isHeatmapChartVisible, + isLive, + setIsLive, +}: { + isHeatmapChartVisible: boolean; + isLive: boolean; + setIsLive: (isLive: boolean) => unknown; +}) { + useEffect(() => { + if (isHeatmapChartVisible && isLive) { + setIsLive(false); + } + }, [isHeatmapChartVisible, isLive, setIsLive]); +} diff --git a/packages/app/src/components/Search/useTraceChartModeReset.ts b/packages/app/src/components/Search/useTraceChartModeReset.ts new file mode 100644 index 0000000000..4cf8f158cd --- /dev/null +++ b/packages/app/src/components/Search/useTraceChartModeReset.ts @@ -0,0 +1,39 @@ +import { useCallback, useEffect, useRef } from 'react'; + +import type { TraceChartMode } from './TraceRedMetricsChart'; + +/** + * Resets the trace RED/Heatmap choice to RED after the user picks a source, + * so coming back to a trace source doesn't silently reopen the heatmap. The + * page arms it on a pick, and it fires once the searched source reaches that + * pick, so it lands on the new history entry; Back/Forward never arm it, and + * an undone pick disarms it. It clears the param: nuqs 1.x would write 'red'. + */ +export function useTraceChartModeReset({ + searchedSourceId, + setTraceChartMode, +}: { + searchedSourceId: string | undefined; + setTraceChartMode: (mode: TraceChartMode | null) => unknown; +}) { + const pendingSourceIdRef = useRef(null); + + useEffect(() => { + if ( + pendingSourceIdRef.current != null && + pendingSourceIdRef.current === searchedSourceId + ) { + pendingSourceIdRef.current = null; + setTraceChartMode(null); + } + }, [searchedSourceId, setTraceChartMode]); + + const arm = useCallback((sourceId: string | null) => { + pendingSourceIdRef.current = sourceId; + }, []); + const disarm = useCallback(() => { + pendingSourceIdRef.current = null; + }, []); + + return { arm, disarm }; +}