Skip to content

Commit cc8eaa1

Browse files
committed
feat: Support heatmaps on prometheus histograms
1 parent fc73f3a commit cc8eaa1

38 files changed

Lines changed: 1331 additions & 171 deletions
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
"@hyperdx/common-utils": patch
3+
"@hyperdx/app": patch
4+
---
5+
6+
feat: Support histogram heatmaps from PromQL bucket metrics

‎packages/app/src/components/ChartDisplaySettingsDrawer.tsx‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,9 @@ import { isTimeSeriesDisplayType } from '@hyperdx/common-utils/dist/core/utils';
88
import {
99
ChartConfigWithDateRange,
1010
DisplayType,
11-
HeatmapMode,
1211
MAX_LEGEND_TEMPLATE_LENGTH,
1312
NumberFormat,
13+
PromqlHeatmapMode,
1414
} from '@hyperdx/common-utils/dist/types';
1515
import {
1616
Alert,
@@ -89,8 +89,8 @@ interface ChartDisplaySettingsDrawerProps {
8989
configType?: 'sql' | 'builder' | 'promql';
9090
/** Whether a PromQL tile's queried expression runs over a range. */
9191
promqlUsesRange?: boolean;
92-
/** A builder heatmap's mode; only distribution heatmaps have a numeric y axis to scale. */
93-
heatmapMode?: HeatmapMode;
92+
/** A heatmap's mode; only distribution heatmaps have a numeric y axis to scale. */
93+
heatmapMode?: PromqlHeatmapMode;
9494
/** The heatmap scale used when the tile has none set. */
9595
defaultHeatmapScaleType?: HeatmapScaleType;
9696
previousDateRange?: [Date, Date];
@@ -227,13 +227,14 @@ export default function ChartDisplaySettingsDrawer({
227227
displayType === DisplayType.Heatmap && heatmapMode === 'distribution';
228228

229229
// Every PromQL display that surfaces a series name. A number tile shows one
230-
// value, a table gives each label its own column, and a distribution heatmap
231-
// merges every series into one, so none has a legend.
230+
// value, a table gives each label its own column, a distribution heatmap
231+
// merges every series into one, and a histogram heatmap labels rows by
232+
// bucket, so none has a legend.
232233
const showLegendTemplate =
233234
configType === 'promql' &&
234235
displayType !== DisplayType.Number &&
235236
displayType !== DisplayType.Table &&
236-
!isDistributionHeatmap;
237+
!(displayType === DisplayType.Heatmap && heatmapMode !== 'series');
237238

238239
// On pie/bar builder charts, seriesLimit becomes a plain SQL LIMIT on the
239240
// number of slices/bars; on PromQL it trims the reduced series client-side

‎packages/app/src/components/ChartEditor/PromqlChartEditor.tsx‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@ import {
1212
import { isTimeSeriesDisplayType } from '@hyperdx/common-utils/dist/core/utils';
1313
import {
1414
DisplayType,
15-
HeatmapMode,
1615
MAX_PROMQL_EXPRESSIONS,
16+
PromqlHeatmapMode,
1717
SourceKind,
1818
} from '@hyperdx/common-utils/dist/types';
1919
import { Box, Button, Divider, Flex, Group, Text } from '@mantine/core';
@@ -26,6 +26,7 @@ import { useSource } from '@/source';
2626

2727
import PromqlExpressionEditor from './PromqlExpressionEditor';
2828
import { ChartEditorFormState } from './types';
29+
import { promqlExpressionPlaceholder } from './utils';
2930

3031
export default function PromqlChartEditor({
3132
control,
@@ -41,8 +42,8 @@ export default function PromqlChartEditor({
4142
allowedSourceKinds: SourceKind[];
4243
onSubmit: (suppressErrorNotification?: boolean) => void;
4344
onOpenDisplaySettings: () => void;
44-
heatmapMode: HeatmapMode;
45-
onHeatmapModeChange: (mode: HeatmapMode) => void;
45+
heatmapMode: PromqlHeatmapMode;
46+
onHeatmapModeChange: (mode: PromqlHeatmapMode) => void;
4647
}) {
4748
const {
4849
fields: expressions,
@@ -118,6 +119,7 @@ export default function PromqlChartEditor({
118119
<HeatmapModeControl
119120
mode={heatmapMode}
120121
onModeChange={onHeatmapModeChange}
122+
allowHistogram
121123
/>
122124
</Box>
123125
)}
@@ -128,6 +130,7 @@ export default function PromqlChartEditor({
128130
index={index}
129131
length={expressions.length}
130132
metricNames={metricNames}
133+
placeholder={promqlExpressionPlaceholder(displayType, heatmapMode)}
131134
isIgnored={!displayTypeSupportsMultiExpression && index > 0}
132135
isInstantQuerySupported={displayTypeSupportsInstantQuery({
133136
displayType,

‎packages/app/src/components/ChartEditor/PromqlExpressionEditor.tsx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ export default function PromqlExpressionEditor({
1212
index,
1313
length,
1414
metricNames,
15+
placeholder,
1516
isIgnored,
1617
isInstantQuerySupported,
1718
isReducerSupported,
@@ -26,6 +27,7 @@ export default function PromqlExpressionEditor({
2627
index: number;
2728
length: number;
2829
metricNames: string[] | undefined;
30+
placeholder: string;
2931
/** Whether the display type leaves this expression unqueried. */
3032
isIgnored: boolean;
3133
/** Whether the display type lets this expression choose between instant and range queries. */
@@ -62,7 +64,7 @@ export default function PromqlExpressionEditor({
6264
value={expressionField.value ?? ''}
6365
onChange={expressionField.onChange}
6466
onSubmit={() => onSubmit()}
65-
placeholder="rate(http_requests_total{service='api'}[5m])"
67+
placeholder={placeholder}
6668
metricNames={metricNames}
6769
enableMacros
6870
/>

‎packages/app/src/components/ChartEditor/__tests__/utils.test.ts‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import {
1919
convertFormStateToSavedChartConfig,
2020
convertSavedChartConfigToFormState,
2121
getAllowedSourceKinds,
22+
promqlExpressionPlaceholder,
2223
validateChartForm,
2324
} from '@/components/ChartEditor/utils';
2425

@@ -688,6 +689,21 @@ describe('PromQL expressions', () => {
688689
});
689690
});
690691

692+
it('saves a histogram heatmap', () => {
693+
expect(
694+
convertFormStateToSavedChartConfig(
695+
{
696+
...promqlForm(
697+
[{ expression: 'sum by (le) (x_bucket)' }],
698+
DisplayType.Heatmap,
699+
),
700+
heatmap: { mode: 'histogram' },
701+
},
702+
undefined,
703+
),
704+
).toMatchObject({ heatmap: { mode: 'histogram' } });
705+
});
706+
691707
it('queries a heatmap with its heatmap settings', () => {
692708
const result = convertFormStateToChartConfig(
693709
{
@@ -1929,6 +1945,22 @@ describe('validateChartForm', () => {
19291945
expect.objectContaining({ path: 'series.0.valueExpression' }),
19301946
);
19311947
});
1948+
1949+
it('requires a value expression on a builder heatmap left in histogram mode', () => {
1950+
const errors = validateChartForm(
1951+
makeForm({
1952+
displayType: DisplayType.Heatmap,
1953+
source: 'source-trace',
1954+
heatmap: { mode: 'histogram' },
1955+
series: [{ ...seriesItem, valueExpression: '' }],
1956+
}),
1957+
traceSource,
1958+
jest.fn(),
1959+
);
1960+
expect(errors).toContainEqual(
1961+
expect.objectContaining({ path: 'series.0.valueExpression' }),
1962+
);
1963+
});
19321964
});
19331965

19341966
describe('color round-trip (sql/promql Number tile)', () => {
@@ -2082,6 +2114,41 @@ describe('heatmap round-trip', () => {
20822114
});
20832115
});
20842116

2117+
describe('builder heatmap settings', () => {
2118+
const form: ChartEditorFormState = {
2119+
displayType: DisplayType.Heatmap,
2120+
source: 'source-trace',
2121+
where: '',
2122+
series: [{ ...seriesItem, valueExpression: 'Duration' }],
2123+
};
2124+
2125+
it('fall back to distribution mode from PromQL-only histogram mode', () => {
2126+
const histogramForm: ChartEditorFormState = {
2127+
...form,
2128+
heatmap: { mode: 'histogram', scaleType: 'log' },
2129+
};
2130+
expect(
2131+
convertFormStateToSavedChartConfig(histogramForm, traceSource),
2132+
).toHaveProperty('heatmap', { mode: undefined });
2133+
expect(
2134+
convertFormStateToChartConfig(
2135+
histogramForm,
2136+
[new Date(0), new Date(1000)],
2137+
traceSource,
2138+
),
2139+
).toHaveProperty('heatmap', { mode: undefined });
2140+
});
2141+
2142+
it('keep series mode, without PromQL-only settings', () => {
2143+
expect(
2144+
convertFormStateToSavedChartConfig(
2145+
{ ...form, heatmap: { mode: 'series', scaleType: 'log' } },
2146+
traceSource,
2147+
),
2148+
).toHaveProperty('heatmap', { mode: 'series' });
2149+
});
2150+
});
2151+
20852152
describe('metric formulas (HDX-5080)', () => {
20862153
const metricSeriesItem = {
20872154
aggFn: 'avg' as const,
@@ -2489,6 +2556,16 @@ describe('getAllowedSourceKinds', () => {
24892556
).toEqual([SourceKind.Trace]);
24902557
});
24912558

2559+
it('treats a leftover histogram mode on a builder heatmap as distribution', () => {
2560+
expect(
2561+
getAllowedSourceKinds({
2562+
configType: 'builder',
2563+
displayType: DisplayType.Heatmap,
2564+
heatmapMode: 'histogram',
2565+
}),
2566+
).toEqual([SourceKind.Trace]);
2567+
});
2568+
24922569
it('offers only PromQL sources on PromQL heatmap tiles', () => {
24932570
expect(
24942571
getAllowedSourceKinds({
@@ -2499,3 +2576,21 @@ describe('getAllowedSourceKinds', () => {
24992576
).toEqual([SourceKind.Promql]);
25002577
});
25012578
});
2579+
2580+
describe('promqlExpressionPlaceholder', () => {
2581+
it.each([
2582+
['distribution', /_sum\[5m\]\) \/ rate\(.*_count/],
2583+
['series', /^sum by \(service\)/],
2584+
['histogram', /^sum by \(le\) \(rate\(.*_bucket/],
2585+
] as const)('suggests a %s heatmap expression', (mode, pattern) => {
2586+
expect(promqlExpressionPlaceholder(DisplayType.Heatmap, mode)).toMatch(
2587+
pattern,
2588+
);
2589+
});
2590+
2591+
it('suggests the same expression on every non-heatmap chart', () => {
2592+
expect(promqlExpressionPlaceholder(DisplayType.Line, 'histogram')).toBe(
2593+
promqlExpressionPlaceholder(DisplayType.Number, 'distribution'),
2594+
);
2595+
});
2596+
});

‎packages/app/src/components/ChartEditor/types.ts‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,13 @@ export type SavedChartConfigWithSelectArray = Omit<
2828
* `promqlExpressions` is the PromQL counterpart, holding the array form of
2929
* `promqlExpression` (which a saved tile may carry as a bare string).
3030
**/
31-
export type ChartEditorFormState = Partial<BuilderSavedChartConfig> &
31+
export type ChartEditorFormState = Partial<
32+
Omit<BuilderSavedChartConfig, 'heatmap'>
33+
> &
3234
Partial<Omit<RawSqlSavedChartConfig, 'configType'>> &
33-
Partial<Omit<PromqlSavedChartConfig, 'configType'>> & {
35+
Partial<Omit<PromqlSavedChartConfig, 'configType' | 'heatmap'>> & {
36+
// The PromQL settings are a superset of the builder's.
37+
heatmap?: PromqlSavedChartConfig['heatmap'];
3438
alert?: BuilderSavedChartConfig['alert'] & {
3539
id?: string;
3640
createdBy?: AlertWithCreatedBy['createdBy'];

‎packages/app/src/components/ChartEditor/utils.ts‎

Lines changed: 43 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ import {
3232
isRangeThresholdType,
3333
isTraceSource,
3434
PromqlChartConfig,
35+
PromqlHeatmapMode,
3536
PromqlSavedChartConfig,
3637
PromqlSeries,
3738
RawSqlChartConfig,
@@ -228,13 +229,13 @@ export function getAllowedSourceKinds({
228229
}: {
229230
configType: ChartEditorFormState['configType'];
230231
displayType: DisplayType | undefined;
231-
heatmapMode?: HeatmapMode;
232+
heatmapMode?: PromqlHeatmapMode;
232233
}): SourceKind[] {
233234
if (configType === 'promql' && isPromqlDisplayType(displayType)) {
234235
return [SourceKind.Promql];
235236
}
236237
if (displayType === DisplayType.Heatmap) {
237-
return [...getHeatmapSourceKinds(heatmapMode)];
238+
return [...getHeatmapSourceKinds(toBuilderHeatmapMode(heatmapMode))];
238239
}
239240
if (isStringSelectDisplayType(displayType)) {
240241
return ROW_LISTING_SOURCE_KINDS;
@@ -324,6 +325,7 @@ export function convertFormStateToSavedChartConfig(
324325
'promqlExpression',
325326
'promqlExpressions',
326327
]),
328+
heatmap: formBuilderHeatmap(form),
327329
select: [],
328330
where: form.where ?? '',
329331
source: source?.id ?? form.source ?? '',
@@ -342,6 +344,7 @@ export function convertFormStateToSavedChartConfig(
342344
'promqlExpression',
343345
'promqlExpressions',
344346
]),
347+
heatmap: formBuilderHeatmap(form),
345348
select: isStringSelectDisplayType(form.displayType)
346349
? typeof form.select === 'string'
347350
? form.select
@@ -446,6 +449,7 @@ export function convertFormStateToChartConfig(
446449
'promqlExpression',
447450
'promqlExpressions',
448451
]),
452+
heatmap: formBuilderHeatmap(form),
449453
from: source.from,
450454
timestampValueExpression: source.timestampValueExpression,
451455
dateRange,
@@ -554,6 +558,42 @@ function formPromqlExpressions(form: ChartEditorFormState): PromqlSeries[] {
554558
}));
555559
}
556560

561+
/** The form's heatmap settings, formatted for a builder tile */
562+
function formBuilderHeatmap(
563+
form: ChartEditorFormState,
564+
): BuilderSavedChartConfig['heatmap'] {
565+
return form.heatmap == null
566+
? undefined
567+
: { mode: toBuilderHeatmapMode(form.heatmap.mode) };
568+
}
569+
570+
/** A heatmap mode as a builder heatmap's, which has no histogram mode. */
571+
export function toBuilderHeatmapMode(
572+
mode: PromqlHeatmapMode | undefined,
573+
): HeatmapMode | undefined {
574+
return mode === 'histogram' ? undefined : mode;
575+
}
576+
577+
const DEFAULT_PROMQL_PLACEHOLDER =
578+
"rate(http_requests_total{service='api'}[5m])";
579+
580+
const PROMQL_HEATMAP_PLACEHOLDERS: Record<PromqlHeatmapMode, string> = {
581+
distribution:
582+
'rate(http_request_duration_seconds_sum[5m]) / rate(http_request_duration_seconds_count[5m])',
583+
series: 'sum by (service) (rate(http_requests_total[5m]))',
584+
histogram: 'sum by (le) (rate(http_request_duration_seconds_bucket[5m]))',
585+
};
586+
587+
/** An example PromQL expression suited to the display type and heatmap mode. */
588+
export function promqlExpressionPlaceholder(
589+
displayType: DisplayType | undefined,
590+
heatmapMode: PromqlHeatmapMode,
591+
): string {
592+
return displayType === DisplayType.Heatmap
593+
? PROMQL_HEATMAP_PLACEHOLDERS[heatmapMode]
594+
: DEFAULT_PROMQL_PLACEHOLDER;
595+
}
596+
557597
/** Heatmap settings are dropped from PromQL tiles that are not heatmaps. */
558598
function formPromqlHeatmap(
559599
form: ChartEditorFormState,
@@ -762,7 +802,7 @@ export const validateChartForm = (
762802
!isRawSqlChart &&
763803
!isPromqlChart &&
764804
form.displayType === DisplayType.Heatmap &&
765-
getHeatmapMode(form) === 'distribution' &&
805+
getHeatmapMode({ heatmap: formBuilderHeatmap(form) }) === 'distribution' &&
766806
Array.isArray(form.series) &&
767807
form.series.length > 0 &&
768808
!form.series[0]?.valueExpression

‎packages/app/src/components/DBEditTimeChartForm/ChartPreviewPanel.tsx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -106,8 +106,8 @@ function HeatmapSQLPreview({
106106
};
107107
const query = toHeatmapQuery(configWithTimestamp);
108108

109-
// Only PromQL heatmaps are calculated, and they have no SQL to preview
110-
if (query.mode === 'calculated') {
109+
// Only PromQL heatmaps are calculated or histograms, and they have no SQL
110+
if (query.mode === 'calculated' || query.mode === 'histogram') {
111111
return null;
112112
}
113113

0 commit comments

Comments
 (0)