From 3a9bdf632b0b205fdbb60098407ef9a087a1cce4 Mon Sep 17 00:00:00 2001 From: Drew Davis Date: Tue, 6 Oct 2026 16:16:04 -0400 Subject: [PATCH 1/4] fix: Respect explicit granularity on heatmaps --- .changeset/heatmap-granularity.md | 5 ++ packages/app/src/DBDashboardPage.tsx | 6 +- .../DBEditTimeChartForm/ChartActionBar.tsx | 8 +- .../DBEditTimeChartForm/ChartPreviewPanel.tsx | 23 ++++-- .../__tests__/ChartActionBar.test.tsx | 11 ++- .../__tests__/ChartPreviewPanel.test.tsx | 3 + .../__tests__/utils.test.ts | 28 +++++++ .../components/DBEditTimeChartForm/utils.ts | 8 +- .../__tests__/heatmapQueries.test.ts | 64 ++++++++++++++++ .../__tests__/useHeatmapData.test.ts | 75 +++++++++++++++++++ .../__tests__/useSeriesHeatmapData.test.ts | 26 +++++++ .../DBHeatmapChart/heatmapQueries.ts | 26 ++++++- .../src/components/DBHeatmapChart/index.ts | 1 + .../DBHeatmapChart/useHeatmapData.ts | 7 +- .../DBHeatmapChart/useHeatmapView.ts | 9 ++- .../DBHeatmapChart/useSeriesHeatmapData.ts | 2 +- .../e2e/components/ChartEditorComponent.ts | 10 +++ .../tests/e2e/features/heatmap-series.spec.ts | 28 +++++++ 18 files changed, 314 insertions(+), 26 deletions(-) create mode 100644 .changeset/heatmap-granularity.md create mode 100644 packages/app/src/components/DBHeatmapChart/__tests__/heatmapQueries.test.ts create mode 100644 packages/app/src/components/DBHeatmapChart/__tests__/useHeatmapData.test.ts diff --git a/.changeset/heatmap-granularity.md b/.changeset/heatmap-granularity.md new file mode 100644 index 0000000000..149efe717c --- /dev/null +++ b/.changeset/heatmap-granularity.md @@ -0,0 +1,5 @@ +--- +'@hyperdx/app': patch +--- + +feat: Respect explicit and minimum granularity on heatmaps diff --git a/packages/app/src/DBDashboardPage.tsx b/packages/app/src/DBDashboardPage.tsx index 41e19d39b9..c4473647f4 100644 --- a/packages/app/src/DBDashboardPage.tsx +++ b/packages/app/src/DBDashboardPage.tsx @@ -161,6 +161,7 @@ import { useDeleteDashboard, } from '@/dashboard'; import { useAlertAnnotations } from '@/hooks/useAlertAnnotations'; +import { getMinGranularitySeconds } from '@/hooks/useChartConfig'; import useDashboardContainers, { TabDeleteAction, } from '@/hooks/useDashboardContainers'; @@ -248,7 +249,10 @@ function HeatmapTile({ dateRange: [Date, Date]; enabled?: boolean; }) { - const heatmapQuery = toHeatmapQuery(queriedConfig); + const heatmapQuery = toHeatmapQuery({ + ...queriedConfig, + minGranularitySeconds: getMinGranularitySeconds(source), + }); const { mode } = heatmapQuery; const [clickPos, setClickPos] = useState<{ x: number; y: number } | null>( diff --git a/packages/app/src/components/DBEditTimeChartForm/ChartActionBar.tsx b/packages/app/src/components/DBEditTimeChartForm/ChartActionBar.tsx index 6b58c4aedc..0929551d54 100644 --- a/packages/app/src/components/DBEditTimeChartForm/ChartActionBar.tsx +++ b/packages/app/src/components/DBEditTimeChartForm/ChartActionBar.tsx @@ -128,11 +128,13 @@ export function ChartActionBar({ const displayType = useWatch({ control, name: 'displayType' }); const promqlExpressions = useWatch({ control, name: 'promqlExpressions' }); - // A time chart always buckets, and a PromQL tile that reduces a range query - // reads the same granularity even though it shows one value rather than a - // series. An all-instant PromQL tile has no resolution to choose. + // Time charts and heatmaps always bucket, and a PromQL tile that reduces a + // range query reads the same granularity even though it shows one value + // rather than a series. An all-instant PromQL tile has no resolution to + // choose. const showGranularity = activeTab === 'time' || + activeTab === 'heatmap' || (configType === 'promql' && isPromqlDisplayType(displayType) && isRangeQuery({ diff --git a/packages/app/src/components/DBEditTimeChartForm/ChartPreviewPanel.tsx b/packages/app/src/components/DBEditTimeChartForm/ChartPreviewPanel.tsx index c15f0687cc..e540f5663a 100644 --- a/packages/app/src/components/DBEditTimeChartForm/ChartPreviewPanel.tsx +++ b/packages/app/src/components/DBEditTimeChartForm/ChartPreviewPanel.tsx @@ -1,5 +1,4 @@ import { useCallback, useMemo, useState } from 'react'; -import { convertDateRangeToGranularityString } from '@hyperdx/common-utils/dist/core/utils'; import { isBuilderChartConfig } from '@hyperdx/common-utils/dist/guards'; import { BuilderChartConfigWithDateRange, @@ -27,6 +26,7 @@ import DBHeatmapChart, { buildHeatmapBucketConfig, buildHeatmapSeriesConfig, HEATMAP_N_BUCKETS, + resolveHeatmapGranularity, toHeatmapQuery, } from '@/components/DBHeatmapChart'; import DBNumberChart from '@/components/DBNumberChart'; @@ -62,13 +62,15 @@ const RUN_TO_PREVIEW = 'Run the query to see the preview'; function HeatmapPreview({ config, + minGranularitySeconds, }: { config: BuilderChartConfigWithDateRange; + minGranularitySeconds: number | undefined; }) { return (
@@ -99,20 +101,24 @@ function HeatmapSQLPreview({ timestampValueExpression, }; const query = toHeatmapQuery(configWithTimestamp); - const granularity = convertDateRangeToGranularityString(dateRange, 245); if (query.mode === 'series') { + const seriesConfig = { ...query.config, dateRange }; return ( ); } const { config: heatmapConfig, scaleType } = query; + const granularity = resolveHeatmapGranularity({ + granularity: heatmapConfig.granularity, + dateRange, + }); const boundsConfig = buildHeatmapBoundsConfig({ config: heatmapConfig, @@ -338,7 +344,12 @@ export function ChartPreviewPanel({ {queryReady && queriedConfig != null && isBuilderChartConfig(queriedConfig) && - activeTab === 'heatmap' && } + activeTab === 'heatmap' && ( + + )} {queryReady && tableSource && queriedConfig != null && diff --git a/packages/app/src/components/DBEditTimeChartForm/__tests__/ChartActionBar.test.tsx b/packages/app/src/components/DBEditTimeChartForm/__tests__/ChartActionBar.test.tsx index 1e8b0b03c6..2e461e35e5 100644 --- a/packages/app/src/components/DBEditTimeChartForm/__tests__/ChartActionBar.test.tsx +++ b/packages/app/src/components/DBEditTimeChartForm/__tests__/ChartActionBar.test.tsx @@ -220,11 +220,14 @@ describe('ChartActionBar', () => { expect(onSubmit).toHaveBeenCalledTimes(1); }); - it('should render granularity picker for time tab', () => { - renderActionBar({ activeTab: 'time' }); + it.each(['time', 'heatmap'])( + 'should render granularity picker for %s tab', + activeTab => { + renderActionBar({ activeTab }); - expect(screen.getByTestId('granularity-picker')).toBeInTheDocument(); - }); + expect(screen.getByTestId('granularity-picker')).toBeInTheDocument(); + }, + ); it('should not render granularity picker for non-time tabs', () => { renderActionBar({ activeTab: 'table' }); diff --git a/packages/app/src/components/DBEditTimeChartForm/__tests__/ChartPreviewPanel.test.tsx b/packages/app/src/components/DBEditTimeChartForm/__tests__/ChartPreviewPanel.test.tsx index d9e4be0d42..609fff93df 100644 --- a/packages/app/src/components/DBEditTimeChartForm/__tests__/ChartPreviewPanel.test.tsx +++ b/packages/app/src/components/DBEditTimeChartForm/__tests__/ChartPreviewPanel.test.tsx @@ -63,6 +63,9 @@ jest.mock('@/components/DBHeatmapChart', () => ({ buildHeatmapBoundsConfig: ({ config }: { config: unknown }) => config, buildHeatmapBucketConfig: ({ config }: { config: unknown }) => config, buildHeatmapSeriesConfig: (config: unknown) => config, + resolveHeatmapGranularity: jest.requireActual( + '@/components/DBHeatmapChart/heatmapQueries', + ).resolveHeatmapGranularity, HEATMAP_N_BUCKETS: 80, })); diff --git a/packages/app/src/components/DBEditTimeChartForm/__tests__/utils.test.ts b/packages/app/src/components/DBEditTimeChartForm/__tests__/utils.test.ts index a71218d755..b83909d9eb 100644 --- a/packages/app/src/components/DBEditTimeChartForm/__tests__/utils.test.ts +++ b/packages/app/src/components/DBEditTimeChartForm/__tests__/utils.test.ts @@ -1036,6 +1036,34 @@ describe('buildChartConfigForExplanations', () => { }, ); + it("carries the source's minimum auto granularity on the heatmap tab", () => { + const result = buildChartConfigForExplanations({ + ...baseParams, + queriedConfig: builderConfig, + queriedSourceId: 'metric-source', + tableSource: { + kind: SourceKind.Metric, + id: 'metric-source', + name: 'Metrics', + from: { databaseName: 'default', tableName: '' }, + connection: 'clickhouse', + timestampValueExpression: 'Timestamp', + resourceAttributesExpression: 'ResourceAttributes', + metricTables: { + gauge: 'metrics.gauge', + sum: 'metrics.sum', + histogram: 'metrics.histogram', + summary: 'metrics.summary', + 'exponential histogram': 'metrics.exp_histogram', + }, + minAutoGranularity: '5 minute', + } satisfies Extract, + activeTab: 'heatmap', + }); + + expect(result?.minGranularitySeconds).toBe(300); + }); + it('falls back to chartConfig when queriedSource does not match', () => { const result = buildChartConfigForExplanations({ ...baseParams, diff --git a/packages/app/src/components/DBEditTimeChartForm/utils.ts b/packages/app/src/components/DBEditTimeChartForm/utils.ts index f42a957970..34ed6a2206 100644 --- a/packages/app/src/components/DBEditTimeChartForm/utils.ts +++ b/packages/app/src/components/DBEditTimeChartForm/utils.ts @@ -432,9 +432,9 @@ export function buildChartConfigForExplanations({ // so that the MV optimization explanation and generated SQL preview // are accurate. Heatmap is special-cased: it actually runs as two // sequential queries (bounds + bucketed counts) that depend on each - // other at runtime, so the SQL preview transforms `config` itself into - // both queries on render and the MV indicator is suppressed for this - // tab. Returning `config` unchanged is intentional. + // other at runtime, so the SQL preview transforms `builderConfig` itself + // into both queries on render and the MV indicator is suppressed for this + // tab. const builderConfig: BuilderChartConfigWithDateRange = { ...config, minGranularitySeconds: getMinGranularitySeconds(tableSource), @@ -449,7 +449,7 @@ export function buildChartConfigForExplanations({ } else if (activeTab === 'pie' || activeTab === 'bar') { return convertToCategoricalChartConfig(builderConfig); } else if (activeTab === 'heatmap') { - return config; + return builderConfig; } return config; diff --git a/packages/app/src/components/DBHeatmapChart/__tests__/heatmapQueries.test.ts b/packages/app/src/components/DBHeatmapChart/__tests__/heatmapQueries.test.ts new file mode 100644 index 0000000000..c3891ac9f0 --- /dev/null +++ b/packages/app/src/components/DBHeatmapChart/__tests__/heatmapQueries.test.ts @@ -0,0 +1,64 @@ +import { + BuilderChartConfigWithDateRange, + DisplayType, +} from '@hyperdx/common-utils/dist/types'; + +import { + resolveHeatmapGranularity, + toHeatmapQuery, +} from '@/components/DBHeatmapChart/heatmapQueries'; + +const HOUR = 60 * 60 * 1000; +const T0 = new Date('2026-07-06T00:00:00Z').getTime(); +const dateRange: [Date, Date] = [new Date(T0), new Date(T0 + 2 * HOUR)]; + +describe('resolveHeatmapGranularity', () => { + it('auto-sizes to about 245 buckets', () => { + // 2h / 245 ≈ 29s + expect(resolveHeatmapGranularity({ dateRange })).toBe('30 second'); + expect(resolveHeatmapGranularity({ granularity: 'auto', dateRange })).toBe( + '30 second', + ); + }); + + it('keeps an explicit granularity', () => { + expect( + resolveHeatmapGranularity({ granularity: '15 minute', dateRange }), + ).toBe('15 minute'); + }); + + it('floors only auto granularity at minGranularitySeconds', () => { + expect( + resolveHeatmapGranularity({ dateRange, minGranularitySeconds: 300 }), + ).toBe('5 minute'); + expect( + resolveHeatmapGranularity({ + granularity: '1 minute', + dateRange, + minGranularitySeconds: 300, + }), + ).toBe('1 minute'); + }); +}); + +describe('toHeatmapQuery', () => { + const config: BuilderChartConfigWithDateRange = { + displayType: DisplayType.Heatmap, + select: [{ aggFn: 'count', aggCondition: '', valueExpression: 'Duration' }], + from: { databaseName: 'default', tableName: 'otel_traces' }, + where: '', + dateRange, + granularity: '5 minute', + timestampValueExpression: 'Timestamp', + connection: 'test-connection', + }; + + it.each(['distribution', 'series'] as const)( + 'keeps the granularity in %s mode', + mode => { + const query = toHeatmapQuery({ ...config, heatmap: { mode } }); + expect(query.mode).toBe(mode); + expect(query.config.granularity).toBe('5 minute'); + }, + ); +}); diff --git a/packages/app/src/components/DBHeatmapChart/__tests__/useHeatmapData.test.ts b/packages/app/src/components/DBHeatmapChart/__tests__/useHeatmapData.test.ts new file mode 100644 index 0000000000..05eae4425d --- /dev/null +++ b/packages/app/src/components/DBHeatmapChart/__tests__/useHeatmapData.test.ts @@ -0,0 +1,75 @@ +import { + BuilderChartConfigWithDateRange, + DisplayType, +} from '@hyperdx/common-utils/dist/types'; +import { renderHook } from '@testing-library/react'; + +import { toHeatmapQuery } from '@/components/DBHeatmapChart/heatmapQueries'; +import { useHeatmapData } from '@/components/DBHeatmapChart/useHeatmapData'; + +const mockUseQueriedChartConfig = jest.fn(); +jest.mock('@/hooks/useChartConfig', () => ({ + useQueriedChartConfig: (...args: unknown[]) => + mockUseQueriedChartConfig(...args), +})); + +const HOUR = 60 * 60 * 1000; +const T0 = new Date('2026-07-06T00:00:00Z').getTime(); + +const traceConfig: BuilderChartConfigWithDateRange = { + displayType: DisplayType.Heatmap, + select: [{ aggFn: 'count', aggCondition: '', valueExpression: 'Duration' }], + from: { databaseName: 'default', tableName: 'otel_traces' }, + where: '', + dateRange: [new Date(T0), new Date(T0 + 2 * HOUR)], + granularity: 'auto', + timestampValueExpression: 'Timestamp', + connection: 'test-connection', +}; + +function renderDistributionHeatmap(config: BuilderChartConfigWithDateRange) { + const query = toHeatmapQuery(config); + if (query.mode !== 'distribution') throw new Error('Expected distribution'); + const { result } = renderHook(() => + useHeatmapData({ + config: query.config, + scaleType: query.scaleType, + enabled: true, + }), + ); + const bucketQuery = mockUseQueriedChartConfig.mock.calls + .filter(([, options]) => options?.queryKey?.[0] === 'heatmap_bucket') + .at(-1)?.[0]; + return { view: result.current.view, bucketQuery }; +} + +describe('useHeatmapData', () => { + beforeEach(() => { + mockUseQueriedChartConfig.mockReset(); + mockUseQueriedChartConfig.mockReturnValue({ + data: { data: [{ min: '1', max: '100' }], meta: [] }, + isLoading: false, + isPlaceholderData: false, + error: null, + }); + }); + + it('buckets at an explicit granularity', () => { + const { view, bucketQuery } = renderDistributionHeatmap({ + ...traceConfig, + granularity: '15 minute', + }); + + expect(bucketQuery.granularity).toBe('15 minute'); + expect(view.generatedTsBuckets).toHaveLength(8); + }); + + it("ignores the source's minimum granularity", () => { + const { bucketQuery } = renderDistributionHeatmap({ + ...traceConfig, + minGranularitySeconds: 300, + }); + + expect(bucketQuery.granularity).toBe('30 second'); + }); +}); diff --git a/packages/app/src/components/DBHeatmapChart/__tests__/useSeriesHeatmapData.test.ts b/packages/app/src/components/DBHeatmapChart/__tests__/useSeriesHeatmapData.test.ts index 34c89fb799..53c32da3f1 100644 --- a/packages/app/src/components/DBHeatmapChart/__tests__/useSeriesHeatmapData.test.ts +++ b/packages/app/src/components/DBHeatmapChart/__tests__/useSeriesHeatmapData.test.ts @@ -114,6 +114,32 @@ describe('useSeriesHeatmapData', () => { expect(queried.granularity).toBe(`${stepSeconds} second`); }); + it('buckets at an explicit granularity', () => { + mockSeriesQuery(); + const { result } = renderHook(() => + useSeriesHeatmapData({ + config: { ...seriesConfig, granularity: '15 minute' }, + enabled: true, + }), + ); + + expect(optionsFor('heatmap_series')![0].granularity).toBe('15 minute'); + expect(result.current.view.generatedTsBuckets).toHaveLength(8); + }); + + it("floors auto granularity at the source's minimum", () => { + mockSeriesQuery(); + const { result } = renderHook(() => + useSeriesHeatmapData({ + config: { ...seriesConfig, minGranularitySeconds: 300 }, + enabled: true, + }), + ); + + expect(optionsFor('heatmap_series')![0].granularity).toBe('5 minute'); + expect(result.current.view.generatedTsBuckets).toHaveLength(24); + }); + it('keeps the 50 series with the largest peaks', () => { mockSeriesQuery({ ...seriesResponse, diff --git a/packages/app/src/components/DBHeatmapChart/heatmapQueries.ts b/packages/app/src/components/DBHeatmapChart/heatmapQueries.ts index 8e4ecaa82e..7aed4b6754 100644 --- a/packages/app/src/components/DBHeatmapChart/heatmapQueries.ts +++ b/packages/app/src/components/DBHeatmapChart/heatmapQueries.ts @@ -1,4 +1,5 @@ import { getHeatmapMode } from '@hyperdx/common-utils/dist/core/heatmap'; +import { convertDateRangeToGranularityString } from '@hyperdx/common-utils/dist/core/utils'; import { BuilderChartConfigWithDateRange, ChartConfigWithDateRange, @@ -47,6 +48,29 @@ export type HeatmapQuery = config: BuilderChartConfigWithDateRange; }; +const HEATMAP_AUTO_GRANULARITY_BUCKETS = 245; + +/** + * `minGranularitySeconds` floors only auto granularity: an explicit + * granularity is the user's choice and is kept as-is. + */ +export function resolveHeatmapGranularity({ + granularity, + dateRange, + minGranularitySeconds, +}: Pick< + BuilderChartConfigWithDateRange, + 'granularity' | 'dateRange' | 'minGranularitySeconds' +>): SQLInterval { + return granularity == null || granularity === 'auto' + ? convertDateRangeToGranularityString( + dateRange, + HEATMAP_AUTO_GRANULARITY_BUCKETS, + minGranularitySeconds, + ) + : granularity; +} + export function toHeatmapQuery( config: BuilderChartConfigWithDateRange, ): HeatmapQuery { @@ -69,7 +93,7 @@ export function toHeatmapQuery( countExpression: firstSelect?.countExpression, }, ], - granularity: 'auto', + granularity: config.granularity, numberFormat: config.numberFormat, }, scaleType: firstSelect?.heatmapScaleType ?? 'log', diff --git a/packages/app/src/components/DBHeatmapChart/index.ts b/packages/app/src/components/DBHeatmapChart/index.ts index e525c0b837..3621cf7602 100644 --- a/packages/app/src/components/DBHeatmapChart/index.ts +++ b/packages/app/src/components/DBHeatmapChart/index.ts @@ -7,6 +7,7 @@ export { buildHeatmapBoundsConfig, buildHeatmapBucketConfig, buildHeatmapSeriesConfig, + resolveHeatmapGranularity, toHeatmapQuery, } from './heatmapQueries'; export { darkPalette, lightPalette } from './palette'; diff --git a/packages/app/src/components/DBHeatmapChart/useHeatmapData.ts b/packages/app/src/components/DBHeatmapChart/useHeatmapData.ts index 8b81ed18ff..88832f9ee0 100644 --- a/packages/app/src/components/DBHeatmapChart/useHeatmapData.ts +++ b/packages/app/src/components/DBHeatmapChart/useHeatmapData.ts @@ -36,9 +36,10 @@ export function useHeatmapData({ scaleType: HeatmapScaleType; enabled: boolean; }): HeatmapData { - const { granularity, generatedTsBuckets } = useHeatmapTimeBuckets( - config.dateRange, - ); + const { granularity, generatedTsBuckets } = useHeatmapTimeBuckets({ + dateRange: config.dateRange, + granularity: config.granularity, + }); const nBuckets = HEATMAP_N_BUCKETS; // Future: #1914 adds overflow-bucket indicators for smarter range diff --git a/packages/app/src/components/DBHeatmapChart/useHeatmapView.ts b/packages/app/src/components/DBHeatmapChart/useHeatmapView.ts index 4ced4e172f..f45e4b180c 100644 --- a/packages/app/src/components/DBHeatmapChart/useHeatmapView.ts +++ b/packages/app/src/components/DBHeatmapChart/useHeatmapView.ts @@ -1,10 +1,10 @@ import { useMemo, useState } from 'react'; import { ClickHouseQueryError } from '@hyperdx/common-utils/dist/clickhouse'; -import { convertDateRangeToGranularityString } from '@hyperdx/common-utils/dist/core/utils'; import { timeBucketByGranularity } from '@/ChartUtils'; import type { HeatmapGrid, HeatmapScaleType } from './heatmapGrid'; +import { resolveHeatmapGranularity } from './heatmapQueries'; export type HeatmapView = { grid: HeatmapGrid; @@ -25,8 +25,11 @@ export type HeatmapData = { }; /** The heatmap's time columns: bucket starts across the date range. */ -export function useHeatmapTimeBuckets(dateRange: [Date, Date]) { - const granularity = convertDateRangeToGranularityString(dateRange, 245); +export function useHeatmapTimeBuckets( + config: Parameters[0], +) { + const { dateRange } = config; + const granularity = resolveHeatmapGranularity(config); // Memoize so timeBucketByGranularity's fresh Date[] doesn't defeat // the grid memoization downstream. dateRange itself may be a diff --git a/packages/app/src/components/DBHeatmapChart/useSeriesHeatmapData.ts b/packages/app/src/components/DBHeatmapChart/useSeriesHeatmapData.ts index f13139f4b3..8f4dbd93e6 100644 --- a/packages/app/src/components/DBHeatmapChart/useSeriesHeatmapData.ts +++ b/packages/app/src/components/DBHeatmapChart/useSeriesHeatmapData.ts @@ -60,7 +60,7 @@ export function useSeriesHeatmapData({ enabled: boolean; }): HeatmapData { const { granularity, generatedTsBuckets, fromMs, toMs } = - useHeatmapTimeBuckets(config.dateRange); + useHeatmapTimeBuckets(config); const seriesConfig = buildHeatmapSeriesConfig(config, granularity); const { data, isLoading, isPlaceholderData, error } = useQueriedChartConfig( diff --git a/packages/app/tests/e2e/components/ChartEditorComponent.ts b/packages/app/tests/e2e/components/ChartEditorComponent.ts index c9532e0248..81d09d1e64 100644 --- a/packages/app/tests/e2e/components/ChartEditorComponent.ts +++ b/packages/app/tests/e2e/components/ChartEditorComponent.ts @@ -80,6 +80,16 @@ export class ChartEditorComponent { .click(); } + /** The editor's own granularity picker, not the dashboard header's. */ + get granularityPicker(): Locator { + return this.editorForm().getByTestId('granularity-picker'); + } + + async setGranularity(label: string) { + await this.granularityPicker.click(); + await this.page.getByRole('option', { name: label, exact: true }).click(); + } + /** The distribution heatmap's "Value" (y axis) SQL input. */ get heatmapValueInput(): Locator { return this.editorForm() diff --git a/packages/app/tests/e2e/features/heatmap-series.spec.ts b/packages/app/tests/e2e/features/heatmap-series.spec.ts index 04948e3fbc..c391179a8f 100644 --- a/packages/app/tests/e2e/features/heatmap-series.spec.ts +++ b/packages/app/tests/e2e/features/heatmap-series.spec.ts @@ -64,6 +64,34 @@ test.describe('Heatmap modes', { tag: ['@full-stack', '@dashboard'] }, () => { .toContain(whereMarker); }); + test('the editor granularity applies in both heatmap modes', async ({ + page, + }) => { + const dashboardPage = new DashboardPage(page); + const editor = dashboardPage.chartEditor; + + await dashboardPage.goto(); + await dashboardPage.createNewDashboard(); + await dashboardPage.addTile(); + await expect(editor.nameInput).toBeVisible(); + await editor.waitForDataToLoad(); + await editor.setChartType(DisplayType.Heatmap); + await expect(editor.source).toHaveValue(DEFAULT_TRACES_SOURCE_NAME); + + await editor.setGranularity('1 Hour Granularity'); + await editor.runQuery(false); + await editor.openGeneratedSql(); + await expect + .poll(() => editor.getAllGeneratedSqlText()) + .toContain('INTERVAL 1 hour'); + + await editor.setHeatmapMode('Series'); + await editor.openGeneratedSql(); + await expect + .poll(() => editor.getAllGeneratedSqlText()) + .toContain('INTERVAL 1 hour'); + }); + test('series heatmap with a group by renders and persists', async ({ page, }) => { From 282fd169c5a27889e84bf9e809dfe2ad7bea2687 Mon Sep 17 00:00:00 2001 From: Drew Davis Date: Tue, 6 Oct 2026 16:37:37 -0400 Subject: [PATCH 2/4] review: Address comments --- packages/app/src/ChartUtils.tsx | 11 +- packages/app/src/DBDashboardPage.tsx | 9 +- .../DBEditTimeChartForm/ChartPreviewPanel.tsx | 1 + .../__tests__/useHeatmapData.test.ts | 33 +++++- .../DBHeatmapChart/heatmapQueries.ts | 24 +++-- .../DBHeatmapChart/useHeatmapData.ts | 6 +- .../tests/e2e/features/heatmap-series.spec.ts | 102 ++++++++++++++++++ 7 files changed, 168 insertions(+), 18 deletions(-) diff --git a/packages/app/src/ChartUtils.tsx b/packages/app/src/ChartUtils.tsx index 9868c778aa..255a034fed 100644 --- a/packages/app/src/ChartUtils.tsx +++ b/packages/app/src/ChartUtils.tsx @@ -100,13 +100,18 @@ export const DEFAULT_CHART_CONFIG: Omit< alignDateRangeToGranularity: true, }; -function getTimeChartGranularity( - granularity: string | undefined, +export function getTimeChartGranularity( + granularity: T | 'auto' | undefined, dateRange: [Date, Date], minGranularitySeconds?: number, + maxBuckets = 80, ) { return granularity === 'auto' || granularity == null - ? convertDateRangeToGranularityString(dateRange, 80, minGranularitySeconds) + ? convertDateRangeToGranularityString( + dateRange, + maxBuckets, + minGranularitySeconds, + ) : granularity; } diff --git a/packages/app/src/DBDashboardPage.tsx b/packages/app/src/DBDashboardPage.tsx index c4473647f4..a01f6a6681 100644 --- a/packages/app/src/DBDashboardPage.tsx +++ b/packages/app/src/DBDashboardPage.tsx @@ -429,7 +429,7 @@ const Tile = ({ onUpdateChart, onMoveToGroup, moveTargets, - granularity, + granularity: dashboardGranularity, onTimeRangeSelect, filters, variables, @@ -489,6 +489,13 @@ const Tile = ({ const [isFullscreen, setIsFullscreen] = useState(false); const [isFocused, setIsFocused] = useState(false); + // A live dashboard's granularity is the coarse refresh interval; heatmaps + // ignore it and stay on their own finer auto granularity. + const granularity = + isLive && chart.config.displayType === DisplayType.Heatmap + ? undefined + : dashboardGranularity; + // Lazy loading: only fetch a tile's data once it has scrolled into the // browser viewport. React Grid Layout mounts every tile up front, so // without this gating each tile would issue its ClickHouse query diff --git a/packages/app/src/components/DBEditTimeChartForm/ChartPreviewPanel.tsx b/packages/app/src/components/DBEditTimeChartForm/ChartPreviewPanel.tsx index e540f5663a..66e06af4c5 100644 --- a/packages/app/src/components/DBEditTimeChartForm/ChartPreviewPanel.tsx +++ b/packages/app/src/components/DBEditTimeChartForm/ChartPreviewPanel.tsx @@ -123,6 +123,7 @@ function HeatmapSQLPreview({ const boundsConfig = buildHeatmapBoundsConfig({ config: heatmapConfig, scaleType, + granularity, }); const bucketConfig = buildHeatmapBucketConfig({ diff --git a/packages/app/src/components/DBHeatmapChart/__tests__/useHeatmapData.test.ts b/packages/app/src/components/DBHeatmapChart/__tests__/useHeatmapData.test.ts index 05eae4425d..84d4c0594f 100644 --- a/packages/app/src/components/DBHeatmapChart/__tests__/useHeatmapData.test.ts +++ b/packages/app/src/components/DBHeatmapChart/__tests__/useHeatmapData.test.ts @@ -37,10 +37,15 @@ function renderDistributionHeatmap(config: BuilderChartConfigWithDateRange) { enabled: true, }), ); - const bucketQuery = mockUseQueriedChartConfig.mock.calls - .filter(([, options]) => options?.queryKey?.[0] === 'heatmap_bucket') - .at(-1)?.[0]; - return { view: result.current.view, bucketQuery }; + const lastQuery = (key: string) => + mockUseQueriedChartConfig.mock.calls + .filter(([, options]) => options?.queryKey?.[0] === key) + .at(-1)?.[0]; + return { + view: result.current.view, + boundsQuery: lastQuery('heatmap'), + bucketQuery: lastQuery('heatmap_bucket'), + }; } describe('useHeatmapData', () => { @@ -72,4 +77,24 @@ describe('useHeatmapData', () => { expect(bucketQuery.granularity).toBe('30 second'); }); + + it.each([undefined, 'auto' as const])( + 'buckets the inner bounds query of an aggregate value when granularity is %s', + granularity => { + const { boundsQuery } = renderDistributionHeatmap({ + ...traceConfig, + select: [ + { + aggFn: 'count', + aggCondition: '', + valueExpression: 'sum(Duration)', + }, + ], + granularity, + }); + + expect(boundsQuery.timestampValueExpression).toBe('__hdx_time_bucket'); + expect(boundsQuery.with[0].chartConfig.granularity).toBe('30 second'); + }, + ); }); diff --git a/packages/app/src/components/DBHeatmapChart/heatmapQueries.ts b/packages/app/src/components/DBHeatmapChart/heatmapQueries.ts index 7aed4b6754..0a2ecaf012 100644 --- a/packages/app/src/components/DBHeatmapChart/heatmapQueries.ts +++ b/packages/app/src/components/DBHeatmapChart/heatmapQueries.ts @@ -1,5 +1,4 @@ import { getHeatmapMode } from '@hyperdx/common-utils/dist/core/heatmap'; -import { convertDateRangeToGranularityString } from '@hyperdx/common-utils/dist/core/utils'; import { BuilderChartConfigWithDateRange, ChartConfigWithDateRange, @@ -7,7 +6,11 @@ import { SQLInterval, } from '@hyperdx/common-utils/dist/types'; -import { convertToTimeChartConfig, isAggregateFunction } from '@/ChartUtils'; +import { + convertToTimeChartConfig, + getTimeChartGranularity, + isAggregateFunction, +} from '@/ChartUtils'; import { heatmapLowQuantile } from './heatmapBounds'; import type { HeatmapScaleType } from './heatmapGrid'; @@ -62,13 +65,12 @@ export function resolveHeatmapGranularity({ BuilderChartConfigWithDateRange, 'granularity' | 'dateRange' | 'minGranularitySeconds' >): SQLInterval { - return granularity == null || granularity === 'auto' - ? convertDateRangeToGranularityString( - dateRange, - HEATMAP_AUTO_GRANULARITY_BUCKETS, - minGranularitySeconds, - ) - : granularity; + return getTimeChartGranularity( + granularity, + dateRange, + minGranularitySeconds, + HEATMAP_AUTO_GRANULARITY_BUCKETS, + ); } export function toHeatmapQuery( @@ -126,9 +128,11 @@ export function buildHeatmapSeriesConfig( export function buildHeatmapBoundsConfig({ config, scaleType, + granularity, }: { config: HeatmapChartConfig; scaleType: HeatmapScaleType; + granularity: SQLInterval; }): BuilderChartConfigWithDateRange { const valueExpression = config.select[0].valueExpression; const isAggregateExpression = isAggregateFunction(valueExpression); @@ -162,6 +166,8 @@ export function buildHeatmapBoundsConfig({ ...config, select: [{ valueExpression, alias: 'value_calc' }], orderBy: undefined, + // Emits the __hdx_time_bucket column the outer query filters on. + granularity, }, }, ], diff --git a/packages/app/src/components/DBHeatmapChart/useHeatmapData.ts b/packages/app/src/components/DBHeatmapChart/useHeatmapData.ts index 88832f9ee0..b90345f8a7 100644 --- a/packages/app/src/components/DBHeatmapChart/useHeatmapData.ts +++ b/packages/app/src/components/DBHeatmapChart/useHeatmapData.ts @@ -44,7 +44,11 @@ export function useHeatmapData({ // Future: #1914 adds overflow-bucket indicators for smarter range // clamping without hiding spikes. - const minMaxConfig = buildHeatmapBoundsConfig({ config, scaleType }); + const minMaxConfig = buildHeatmapBoundsConfig({ + config, + scaleType, + granularity, + }); const { data: minMaxData, diff --git a/packages/app/tests/e2e/features/heatmap-series.spec.ts b/packages/app/tests/e2e/features/heatmap-series.spec.ts index c391179a8f..93db83a8d3 100644 --- a/packages/app/tests/e2e/features/heatmap-series.spec.ts +++ b/packages/app/tests/e2e/features/heatmap-series.spec.ts @@ -1,5 +1,6 @@ import { DisplayType } from '@hyperdx/common-utils/dist/types'; +import { HeatmapComponent } from '../components/HeatmapComponent'; import { DashboardPage } from '../page-objects/DashboardPage'; import { SERVICES } from '../seed-clickhouse'; import { getApiUrl, getSources } from '../utils/api-helpers'; @@ -267,4 +268,105 @@ test.describe('Heatmap modes', { tag: ['@full-stack', '@dashboard'] }, () => { await expect(page).toHaveURL(/\/search\?.*mode=delta/); }); }); + + test('live dashboard heatmaps keep their auto granularity', async ({ + page, + }) => { + test.setTimeout(120000); + const dashboardPage = new DashboardPage(page); + const ts = Date.now(); + + const traceSource = (await getSources(page, 'trace')).find( + s => s.name === DEFAULT_TRACES_SOURCE_NAME, + ); + expect(traceSource).toBeDefined(); + const heatmapTile = (index: number, valueExpression: string) => ({ + id: `live-heatmap-${index}-${ts}`, + x: index * 12, + y: 0, + w: 12, + h: 10, + config: { + name: `Live heatmap ${valueExpression}`, + displayType: DisplayType.Heatmap, + source: traceSource._id, + select: [ + { + aggFn: 'count', + aggCondition: '', + aggConditionLanguage: 'lucene', + valueExpression, + countExpression: 'count()', + heatmapScaleType: 'log', + }, + ], + where: '', + whereLanguage: 'lucene', + }, + }); + const response = await page.request.post(`${getApiUrl()}/dashboards`, { + data: { + name: `E2E Live Heatmap ${ts}`, + tags: [], + tiles: [ + heatmapTile(0, '(Duration)/1e6'), + // An aggregate value runs its bounds query over a time-bucketed CTE. + heatmapTile(1, 'sum(Duration)/1e6'), + ], + }, + }); + expect(response.ok()).toBe(true); + const { id: dashboardId } = await response.json(); + + const queries: string[] = []; + page.on('request', request => { + if (request.url().includes('/clickhouse-proxy')) { + queries.push(request.postData() ?? ''); + } + }); + // Past 1h: auto heatmap granularity (245 buckets) is 15 seconds; the live + // refresh interval (60 buckets) is 1 minute. + const expectQueriesAt = async (interval: string) => { + await expect.poll(() => queries.join('\n')).toContain(interval); + expect(queries.join('\n')).not.toContain('INTERVAL 1 minute'); + }; + const assertTileRenders = async (index: number) => { + const heatmap = dashboardPage.getTileHeatmap(index); + await expect(heatmap.canvas.first()).toBeVisible({ timeout: 20000 }); + await expect(dashboardPage.getTileError(index)).toHaveCount(0); + await expect(heatmap.notEnoughDataText).toHaveCount(0); + await heatmap.hoverPopulatedCell(); + }; + + await test.step('Both tiles render in live mode', async () => { + // An explicit dashboard granularity makes turning live on re-query. + await page.goto(`/dashboards/${dashboardId}?granularity=5+minute`); + await expectQueriesAt('INTERVAL 5 minute'); + await assertTileRenders(0); + await assertTileRenders(1); + queries.length = 0; + await dashboardPage.toggleLiveMode(); + await expectQueriesAt('INTERVAL 15 second'); + await assertTileRenders(0); + await assertTileRenders(1); + }); + + await test.step('Fullscreen matches the tile granularity', async () => { + queries.length = 0; + // openFullscreenForTile always clicks the first tile's button. + await dashboardPage.hoverOverTile(1); + await dashboardPage + .getTile(1) + .locator('[data-testid^="tile-fullscreen-button-"]') + .click(); + const heatmap = new HeatmapComponent( + page, + dashboardPage.fullscreenModalBody, + ); + await expect(heatmap.canvas.first()).toBeVisible({ timeout: 20000 }); + await expect(heatmap.notEnoughDataText).toHaveCount(0); + await expectQueriesAt('INTERVAL 15 second'); + await dashboardPage.closeFullscreen(); + }); + }); }); From f18f4f65975f1cfc780419ea41cf822ecad025a8 Mon Sep 17 00:00:00 2001 From: Drew Davis Date: Wed, 7 Oct 2026 08:21:45 -0400 Subject: [PATCH 3/4] fix: Fix highlight at edges of heatmap --- .../__tests__/highlightDataPlugin.test.ts | 21 ++++++++++- .../DBHeatmapChart/highlightDataPlugin.ts | 35 ++++++++++++------- 2 files changed, 43 insertions(+), 13 deletions(-) diff --git a/packages/app/src/components/DBHeatmapChart/__tests__/highlightDataPlugin.test.ts b/packages/app/src/components/DBHeatmapChart/__tests__/highlightDataPlugin.test.ts index 85526b5611..c7e246b993 100644 --- a/packages/app/src/components/DBHeatmapChart/__tests__/highlightDataPlugin.test.ts +++ b/packages/app/src/components/DBHeatmapChart/__tests__/highlightDataPlugin.test.ts @@ -16,6 +16,7 @@ function hover( cursor: { left: number; top: number }, cells = [2, 6], cellKind: HeatmapCellKind = 'count', + plotSize = { clientWidth: 200, clientHeight: 100 }, ) { const onPointHighlight = jest.fn(); const plugin = highlightDataPlugin({ @@ -25,7 +26,7 @@ function hover( }); const u = { cursor, - over: { offsetLeft: 5, offsetTop: 7 }, + over: { offsetLeft: 5, offsetTop: 7, ...plotSize }, valToPos, posToVal, data: [ @@ -62,6 +63,24 @@ describe('highlightDataPlugin', () => { }); }); + it('clips the reported box to the plot area', () => { + // The column spans x 95..105; the plot ends at x 100 + expect( + reported( + hover({ left: 98, top: 80 }, [2, 6], 'count', { + clientWidth: 100, + clientHeight: 100, + }), + ), + ).toMatchObject({ + closestIndex: 1, + xCoord: 102.5, + yCoord: 87, + xSize: 5, + ySize: 20, + }); + }); + it('prefers the cell under the cursor over a nearby one', () => { // Just inside row 0, a pixel from row 1's edge expect(reported(hover({ left: 100, top: 91 }))).toMatchObject({ diff --git a/packages/app/src/components/DBHeatmapChart/highlightDataPlugin.ts b/packages/app/src/components/DBHeatmapChart/highlightDataPlugin.ts index f03a78fa0f..653cdf8f64 100644 --- a/packages/app/src/components/DBHeatmapChart/highlightDataPlugin.ts +++ b/packages/app/src/components/DBHeatmapChart/highlightDataPlugin.ts @@ -70,10 +70,16 @@ export function highlightDataPlugin({ const yLo = Math.min(yA, yB); const yHi = Math.max(yA, yB); + // Edge cells extend past the plot area (the first and last columns + // are centered on the range bounds). The canvas clips them, so clip + // the reported box to match. + const plotWidth = u.over.clientWidth; + const plotHeight = u.over.clientHeight; + const clamp = (v: number, max: number) => Math.min(Math.max(v, 0), max); + let closestIndex = -1; let closestDistance = Infinity; - let xSize = 0; - let ySize = 0; + let box = { left: 0, right: 0, top: 0, bottom: 0 }; for (let i = 0; i < xs.length && closestDistance > 0; i++) { if (isEmptyHeatmapCell(counts[i], cellKind)) continue; @@ -85,20 +91,25 @@ export function highlightDataPlugin({ const x1 = u.valToPos(x1s[i], 'x'); const y0 = u.valToPos(y0s[i], 'y'); const y1 = u.valToPos(y1s[i], 'y'); + const cell = { + left: clamp(Math.min(x0, x1), plotWidth), + right: clamp(Math.max(x0, x1), plotWidth), + top: clamp(Math.min(y0, y1), plotHeight), + bottom: clamp(Math.max(y0, y1), plotHeight), + }; const distance = distanceToRect( left, top, - Math.min(x0, x1), - Math.max(x0, x1), - Math.min(y0, y1), - Math.max(y0, y1), + cell.left, + cell.right, + cell.top, + cell.bottom, ); if (distance < closestDistance) { closestIndex = i; closestDistance = distance; - xSize = Math.abs(x1 - x0); - ySize = Math.abs(y1 - y0); + box = cell; } } @@ -115,10 +126,10 @@ export function highlightDataPlugin({ countVal: counts[closestIndex], closestDistance, closestIndex, - xCoord: u.valToPos(xs[closestIndex], 'x') + offsetLeft, - yCoord: u.valToPos(ys[closestIndex], 'y') + offsetTop, - xSize, - ySize, + xCoord: (box.left + box.right) / 2 + offsetLeft, + yCoord: (box.top + box.bottom) / 2 + offsetTop, + xSize: box.right - box.left, + ySize: box.bottom - box.top, }); }, }, From ac755754c094497eaa11745c3ec1911358afff7a Mon Sep 17 00:00:00 2001 From: Drew Davis Date: Wed, 7 Oct 2026 08:51:08 -0400 Subject: [PATCH 4/4] fix: Align heatmap query to granularity --- .../__tests__/useHeatmapData.test.ts | 35 +++++++++++++++++++ .../DBHeatmapChart/heatmapQueries.ts | 8 ++++- 2 files changed, 42 insertions(+), 1 deletion(-) diff --git a/packages/app/src/components/DBHeatmapChart/__tests__/useHeatmapData.test.ts b/packages/app/src/components/DBHeatmapChart/__tests__/useHeatmapData.test.ts index 84d4c0594f..87a5b39501 100644 --- a/packages/app/src/components/DBHeatmapChart/__tests__/useHeatmapData.test.ts +++ b/packages/app/src/components/DBHeatmapChart/__tests__/useHeatmapData.test.ts @@ -97,4 +97,39 @@ describe('useHeatmapData', () => { expect(boundsQuery.with[0].chartConfig.granularity).toBe('30 second'); }, ); + + it('aligns only the bucket-label filter of an aggregate value', () => { + const dateRange: [Date, Date] = [ + new Date(T0 + 5 * 60 * 1000), + new Date(T0 + HOUR + 20 * 60 * 1000), + ]; + const { boundsQuery, bucketQuery } = renderDistributionHeatmap({ + ...traceConfig, + select: [ + { aggFn: 'count', aggCondition: '', valueExpression: 'avg(Duration)' }, + ], + dateRange, + granularity: '1 hour', + }); + + for (const query of [boundsQuery, bucketQuery]) { + expect(query.dateRange).toEqual([new Date(T0), new Date(T0 + 2 * HOUR)]); + expect(query.with[0].chartConfig.dateRange).toEqual(dateRange); + } + }); + + it('keeps the original range for a non-aggregate value', () => { + const dateRange: [Date, Date] = [ + new Date(T0 + 5 * 60 * 1000), + new Date(T0 + HOUR + 20 * 60 * 1000), + ]; + const { boundsQuery, bucketQuery } = renderDistributionHeatmap({ + ...traceConfig, + dateRange, + granularity: '1 hour', + }); + + expect(boundsQuery.dateRange).toEqual(dateRange); + expect(bucketQuery.dateRange).toEqual(dateRange); + }); }); diff --git a/packages/app/src/components/DBHeatmapChart/heatmapQueries.ts b/packages/app/src/components/DBHeatmapChart/heatmapQueries.ts index 0a2ecaf012..74c12f44fe 100644 --- a/packages/app/src/components/DBHeatmapChart/heatmapQueries.ts +++ b/packages/app/src/components/DBHeatmapChart/heatmapQueries.ts @@ -1,4 +1,5 @@ import { getHeatmapMode } from '@hyperdx/common-utils/dist/core/heatmap'; +import { getAlignedDateRange } from '@hyperdx/common-utils/dist/core/utils'; import { BuilderChartConfigWithDateRange, ChartConfigWithDateRange, @@ -172,6 +173,10 @@ export function buildHeatmapBoundsConfig({ }, ], timestampValueExpression: '__hdx_time_bucket', + // The first bucket is labelled before an unaligned start, so align + // this filter on bucket labels. The inner query keeps the original + // range so no events outside it are counted. + dateRange: getAlignedDateRange(config.dateRange, granularity), from: { databaseName: '', tableName: 'min_max_calc' }, } : { @@ -214,7 +219,7 @@ export function buildHeatmapBucketConfig({ scaleType: HeatmapScaleType; effectiveMin: string | number; max: string | number; - granularity: string; + granularity: SQLInterval; nBuckets: number; }): BuilderChartConfigWithDateRange { const valueExpression = config.select[0].valueExpression; @@ -265,6 +270,7 @@ export function buildHeatmapBucketConfig({ }, ], timestampValueExpression: '__hdx_time_bucket', + dateRange: getAlignedDateRange(config.dateRange, granularity), from: { databaseName: '', tableName: 'bucket_calc' }, orderBy: [{ valueExpression: 'x_bucket', ordering: 'ASC' }], granularity,