Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/trace-search-duration-heatmap.md
Original file line number Diff line number Diff line change
@@ -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.
123 changes: 106 additions & 17 deletions packages/app/src/DBSearchPage.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ import {
Group,
Modal,
Paper,
SegmentedControl,
Select,
Stack,
Text,
Expand Down Expand Up @@ -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';
Expand Down Expand Up @@ -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',
Comment thread
alex-fedotyev marked this conversation as resolved.
Resolved
parseAsStringEnum([...TRACE_CHART_MODES]).withDefault('red'),
);

// URL-only, not saved with the search: null uses the source default.
const [groupByParam, setGroupByParam] = useQueryState(
'groupBy',
Expand Down Expand Up @@ -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<string | null>(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<string | null>(null);

const watchedSourceObj = useMemo(
() => inputSourceObjs?.find(s => s.id === watchedSource),
Expand Down Expand Up @@ -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', '');
Expand Down Expand Up @@ -1547,6 +1568,18 @@ function DBSearchPageContent() {
setSearchedConfig,
]);

useEffect(() => {
Comment thread
alex-fedotyev marked this conversation as resolved.
Resolved
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));
Expand Down Expand Up @@ -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) &&
Expand Down Expand Up @@ -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(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — traceHeatmapChartConfig duplicates the delta heatmap's inline config

The delta-mode DBSearchHeatmapChart (DBSearchPage.tsx:2908-2912) builds the same {...chartConfig, dateRange: searchedTimeRange, with: aliasWith} object inline on every render. Pass the memoized traceHeatmapChartConfig there too (renamed to something like heatmapBaseChartConfig) so the base config has one source of truth.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That would change the delta view's code path, which this PR otherwise leaves alone, so I'm keeping it out of this PR.

Comment thread
alex-fedotyev marked this conversation as resolved.
Resolved
Comment thread
alex-fedotyev marked this conversation as resolved.
Resolved
() =>
chartConfig == null
? undefined
: ({
...chartConfig,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — Heatmap config keeps the results table's orderBy, so sorting a column rebuilds the heatmap

Add orderBy: undefined to traceHeatmapChartConfig, the way histogramTimeChartConfig and filtersChartConfig do. The heatmap's query keys already drop orderBy (buildHeatmapBoundsConfig/buildHeatmapBucketConfig in DBHeatmapChart/heatmapQueries.ts). But DistributionHeatmapChart sets plotKey={JSON.stringify(query.config)}, and that string still contains the search's orderBy. So clicking a sort header (onSortingChange → setSearchedConfig({orderBy})) changes chartConfig, which tears down and recreates the uPlot instance even though the data hasn't changed. That is the same rebuild this PR's live-tail guard comment is trying to avoid.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right: sorting the results table changes the plotKey and remounts the heatmap. The fix is orderBy: undefined on traceHeatmapChartConfig, as histogramTimeChartConfig does. I'm leaving it to the reviewer's call on scope rather than another round here.

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 = (
<SearchGroupBySelect
source={searchedSource}
Expand Down Expand Up @@ -2655,7 +2729,7 @@ function DBSearchPageContent() {
setInputValue={setDisplayedTimeInputValue}
onSearch={onTimePickerSearch}
onRelativeSearch={onTimePickerRelativeSearch}
showLive={analysisMode === 'results'}
showLive={analysisMode === 'results' && !isHeatmapChartVisible}
isLiveMode={isLive}
// Default to relative time mode if the user has made changes to interval and reloaded.
defaultRelativeTimeMode={
Expand Down Expand Up @@ -2878,8 +2952,26 @@ function DBSearchPageContent() {
{histogramGroupBySelect}
</SearchResultsCountGroup>
<Group gap="sm" align="center">
{traceChartsSource != null && (
<SegmentedControl
size="xs"
value={traceChartMode}
onChange={v =>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — Switch options are hand-written rather than derived from TRACE_CHART_MODES, and the ?? 'red' fallback never runs

TRACE_CHART_MODES says the view switch reads from it, but the data array lists 'red'/'heatmap' as literals. A new mode added to the list would parse from the URL but never appear in the switch. SegmentedControl only emits values from data, so the find(...) ?? 'red' fallback is dead code. Fix: build data from TRACE_CHART_MODES with a Record<TraceChartMode, string> label map, and narrow v with that list.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The fallback narrows find's possibly-undefined result for the type. A new mode also needs its label in the switch, which sits next to the handler, so I left the two entries inline rather than add a label map.

setTraceChartMode(
TRACE_CHART_MODES.find(
mode => mode === v,
) ?? 'red',
)
}
data={[
Comment thread
alex-fedotyev marked this conversation as resolved.
Resolved
{ label: 'RED', value: 'red' },
{ label: 'Heatmap', value: 'heatmap' },
]}
/>
)}
{shouldShowLiveModeHint &&
denoiseResults != true && (
denoiseResults != true &&
!isHeatmapChartVisible && (
<ResumeLiveTailButton
handleResumeLiveTail={handleResumeLiveTail}
/>
Expand All @@ -2901,25 +2993,22 @@ function DBSearchPageContent() {
</Group>
</Box>
{!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 ? (

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — traceHeatmapChartConfig != null check can never be false here

Remove the check from the branch condition. This branch sits inside chartConfig && histogramTimeChartConfig && totalCountConfig && (line 2922). traceHeatmapChartConfig is only undefined when chartConfig == null, so the RED/Heatmap branch never falls back to the histogram because of it. Building the config inline, or typing the memo as non-null under that guard, would make that clear.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's there for the type: traceHeatmapChartConfig is a memo computed above that JSX guard, so it stays possibly undefined and the prop needs the narrowing.

Comment thread
alex-fedotyev marked this conversation as resolved.
Resolved
Comment thread
alex-fedotyev marked this conversation as resolved.
Resolved
<Box
className={searchPageStyles.timeChartContainer}
mih="0"
h={240}
>
<TraceRedMetricsChart
mode={traceChartMode}
histogramTimeChartConfig={
histogramTimeChartConfig
}
source={traceRedMetricsSource}
heatmapChartConfig={traceHeatmapChartConfig}
source={traceChartsSource}
isReady={isReady}
queryKeyPrefix={RED_QUERY_KEY_PREFIX}
throughputQueryKeyPrefix={QUERY_KEY_PREFIX}
Expand Down
69 changes: 68 additions & 1 deletion packages/app/src/components/Search/TraceRedMetricsChart.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,12 @@ import { Flex, SegmentedControl } from '@mantine/core';

import { IsolatedChartSyncProvider } from '@/chartSync';
import { ChartCard } from '@/components/charts/ChartCard';
import DBHeatmapChart, {
HEATMAP_DURATION_NUMBER_FORMAT,
toHeatmapQuery,
} from '@/components/DBHeatmapChart';
import { DBTimeChart, type SeriesGroupFilter } from '@/components/DBTimeChart';
import { getDurationMsExpression } from '@/source';

import {
durationConfig,
Expand All @@ -18,6 +23,14 @@ import {
redBaseConfig,
} from './traceRedMetrics';

/**
* The trace results chart views, RED first as the default. The URL parser and
* the view switch both read this list, so a new mode can't be added to the type
* alone and silently parse back to RED.
*/
export const TRACE_CHART_MODES = ['red', 'heatmap'] as const;
export type TraceChartMode = (typeof TRACE_CHART_MODES)[number];

// Each RED tile is a ChartCard flex child that fills its column; ChartCard
// supplies the dashboard-tile chrome (border, background, full-bleed header
// divider) and the card-header context, so the three headers line up on their
Expand All @@ -29,27 +42,40 @@ const RED_TILE_STYLE = {
height: '100%',
} satisfies CSSProperties;

const HEATMAP_TILE_STYLE = {
height: '100%',
minHeight: 0,
} satisfies CSSProperties;

/**
* RED metrics (Throughput, Errors, Duration) for the trace search results view,
* replacing the single count histogram. The three charts render side by side as
* sibling DBTimeCharts under a shared sync scope, so hovering one shows a
* cross-chart cursor on all three at the same timestamp.
* cross-chart cursor on all three at the same timestamp. The RED/Heatmap switch
* lives in the search stats row (passed in as `mode`); the Heatmap view is the
* same bare heatmap tile the dashboard renders.
*
* The per-chart aggregations are built by ./traceRedMetrics from the same base
* config the histogram uses, so all three honor the active WHERE filter and
* selected time range.
*/
export function TraceRedMetricsChart({
mode,
histogramTimeChartConfig,
heatmapChartConfig,
source,
isReady,
queryKeyPrefix,
throughputQueryKeyPrefix,
onTimeRangeSelect,
onFocusSeries,
}: {
/** RED vs heatmap; owned by the search stats row so the switch sits inline. */
mode: TraceChartMode;
/** The count-histogram config; RED charts spread this and swap only select. */
histogramTimeChartConfig: BuilderChartConfigWithDateRange;
/** Base config for the heatmap tile, mirroring the delta-mode callsite. */
heatmapChartConfig: BuilderChartConfigWithDateRange;
source: TTraceSource;
isReady: boolean;
/** Query-key prefix for the auxiliary Errors/Duration tiles, kept separate so
Expand Down Expand Up @@ -86,6 +112,34 @@ export function TraceRedMetricsChart({
[base, durationExpression],
);

// The heatmap plots getDurationMsExpression (the source's duration already
// scaled to ms by its durationPrecision), which is the value
// HEATMAP_DURATION_NUMBER_FORMAT is paired with.
const durationMsExpression = getDurationMsExpression(source);
/**
Comment thread
alex-fedotyev marked this conversation as resolved.
Resolved
* Heatmap tile query (duration distribution over time), matching the
* dashboard heatmap tile: no significant-fields comparison panel. It is the
* query the delta view's heatmap builds with its default settings, but the
* value, count and scale are fixed here rather than read from that view's
* settings drawer, so this stays a plain duration heatmap independent of the
* delta view's query state.
*/
const heatmapQuery = useMemo(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — Duration heatmap query is copied from DBSearchHeatmapChart and marked with an @source tag instead of shared

Lines 121-135 rebuild the same toHeatmapQuery({...config, select:[{valueExpression: getDurationMsExpression(source), countExpression:'count()', heatmapScaleType:'log'}], numberFormat: HEATMAP_DURATION_NUMBER_FORMAT}) that components/Search/DBSearchHeatmapChart.tsx:142-155 builds. The conventions reserve @source for whole-file ports across packages. Fix: extract a toDurationHeatmapQuery(config, source, {value, count, scaleType}) helper next to toHeatmapQuery and call it from both places.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dropped the @source tag in b1a88cb. I kept the query inline: the delta view reads value, count and scale from its settings drawer and only attaches the duration format when the value is the duration expression, so a shared helper would mostly be parameters, and it would touch DBSearchHeatmapChart.tsx, which this PR doesn't change.

Comment thread
alex-fedotyev marked this conversation as resolved.
Resolved
() =>
toHeatmapQuery({
...heatmapChartConfig,
select: [
{
valueExpression: durationMsExpression,
countExpression: 'count()',
heatmapScaleType: 'log',
},
],
numberFormat: HEATMAP_DURATION_NUMBER_FORMAT,
}),
[heatmapChartConfig, durationMsExpression],
);

const errorsModeControl = (
<SegmentedControl
key="errors-mode"
Expand Down Expand Up @@ -118,6 +172,19 @@ export function TraceRedMetricsChart({
// of surfacing the raw aggregate expression as a label.
const throughputGrouped = isUsingGroupBy(histogramTimeChartConfig);

if (mode === 'heatmap') {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — The new heatmap branch of TraceRedMetricsChart has no test

Add a component test that renders mode="heatmap" and checks that DBHeatmapChart gets a distribution query whose value is getDurationMsExpression(source), uses HEATMAP_DURATION_NUMBER_FORMAT and log scale, and receives queryKeyPrefix. Today only the guard hook and useHeatmapData keys are tested, so a wrong expression or format here would still pass (there is no TraceRedMetricsChart test under components/Search/__tests__/).

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not adding a component test here: the branch is checked on the preview (duration value, ms format, log scale), and e2e for the view, which covers it end to end, is tracked in #3176.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — TraceRedMetricsChart now renders two unrelated views behind a mode early return

In heatmap mode the component still computes the RED configs and receives props it doesn't use (onFocusSeries, throughputQueryKeyPrefix, histogram config). In RED mode it needs heatmapChartConfig, and DBSearchPage now gates the RED tiles on traceHeatmapChartConfig != null. This breaks the Single Responsibility convention. Fix: add a separate small TraceDurationHeatmapChart and pick between the two in DBSearchPage on traceChartMode. TraceRedMetricsChart then stays RED-only.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Keeping one component: both views take the same search config, source and ready state, and the page picks the view in one place. A second component would carry the same props without changing behavior.

return (
<ChartCard style={HEATMAP_TILE_STYLE}>
<DBHeatmapChart
title="Duration"
query={heatmapQuery}
enabled={isReady}
showLegend
/>
</ChartCard>
);
}

return (
<IsolatedChartSyncProvider>
<Flex direction="row" h="100%" gap="sm" mih="0" miw="0">
Expand Down
Original file line number Diff line number Diff line change
@@ -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();
});
});
Loading
Loading