Skip to content
Merged
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/heatmap-granularity.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@hyperdx/app': patch
---

feat: Respect explicit and minimum granularity on heatmaps
11 changes: 8 additions & 3 deletions packages/app/src/ChartUtils.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -101,13 +101,18 @@ export const DEFAULT_CHART_CONFIG: Omit<
alignDateRangeToGranularity: true,
};

function getTimeChartGranularity(
granularity: string | undefined,
export function getTimeChartGranularity<T extends string>(
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;
}

Expand Down
15 changes: 13 additions & 2 deletions packages/app/src/DBDashboardPage.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -161,6 +161,7 @@ import {
useDeleteDashboard,
} from '@/dashboard';
import { useAlertAnnotations } from '@/hooks/useAlertAnnotations';
import { getMinGranularitySeconds } from '@/hooks/useChartConfig';
import useDashboardContainers, {
TabDeleteAction,
} from '@/hooks/useDashboardContainers';
Expand Down Expand Up @@ -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>(
Expand Down Expand Up @@ -425,7 +429,7 @@ const Tile = ({
onUpdateChart,
onMoveToGroup,
moveTargets,
granularity,
granularity: dashboardGranularity,
onTimeRangeSelect,
filters,
variables,
Expand Down Expand Up @@ -485,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 =
Comment thread
pulpdrew marked this conversation as resolved.
Resolved
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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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({
Expand Down
Original file line number Diff line number Diff line change
@@ -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,
Expand Down Expand Up @@ -27,6 +26,7 @@ import DBHeatmapChart, {
buildHeatmapBucketConfig,
buildHeatmapSeriesConfig,
HEATMAP_N_BUCKETS,
resolveHeatmapGranularity,
toHeatmapQuery,
} from '@/components/DBHeatmapChart';
import DBNumberChart from '@/components/DBNumberChart';
Expand Down Expand Up @@ -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 (
<div className="flex-grow-1 d-flex flex-column" style={{ height: 400 }}>
<DBHeatmapChart
query={toHeatmapQuery(config)}
query={toHeatmapQuery({ ...config, minGranularitySeconds })}
showLegend
errorVariant="inline"
/>
Expand Down Expand Up @@ -99,24 +101,29 @@ function HeatmapSQLPreview({
timestampValueExpression,
};
const query = toHeatmapQuery(configWithTimestamp);
const granularity = convertDateRangeToGranularityString(dateRange, 245);

if (query.mode === 'series') {
const seriesConfig = { ...query.config, dateRange };
return (
<ChartSQLPreview
config={buildHeatmapSeriesConfig(
{ ...query.config, dateRange },
granularity,
seriesConfig,
resolveHeatmapGranularity(seriesConfig),
)}
enableCopy
/>
);
}
const { config: heatmapConfig, scaleType } = query;
const granularity = resolveHeatmapGranularity({
granularity: heatmapConfig.granularity,
dateRange,
});

const boundsConfig = buildHeatmapBoundsConfig({
config: heatmapConfig,
scaleType,
granularity,
});

const bucketConfig = buildHeatmapBucketConfig({
Expand Down Expand Up @@ -338,7 +345,12 @@ export function ChartPreviewPanel({
{queryReady &&
queriedConfig != null &&
isBuilderChartConfig(queriedConfig) &&
activeTab === 'heatmap' && <HeatmapPreview config={queriedConfig} />}
activeTab === 'heatmap' && (
<HeatmapPreview
config={queriedConfig}
minGranularitySeconds={minGranularitySeconds}
/>
)}
{queryReady &&
tableSource &&
queriedConfig != null &&
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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' });
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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,
}));

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -1038,6 +1038,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<TSource, { kind: SourceKind.Metric }>,
activeTab: 'heatmap',
});

expect(result?.minGranularitySeconds).toBe(300);
});

it('falls back to chartConfig when queriedSource does not match', () => {
const result = buildChartConfigForExplanations({
...baseParams,
Expand Down
8 changes: 4 additions & 4 deletions packages/app/src/components/DBEditTimeChartForm/utils.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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),
Expand All @@ -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;
Expand Down
Original file line number Diff line number Diff line change
@@ -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');
},
);
});
Original file line number Diff line number Diff line change
Expand Up @@ -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({
Expand All @@ -25,7 +26,7 @@ function hover(
});
const u = {
cursor,
over: { offsetLeft: 5, offsetTop: 7 },
over: { offsetLeft: 5, offsetTop: 7, ...plotSize },
valToPos,
posToVal,
data: [
Expand Down Expand Up @@ -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({
Expand Down
Loading
Loading