Skip to content

Commit 9fc2ace

Browse files
committed
feat: Support sparkline on promql number charts
1 parent a8a72c1 commit 9fc2ace

17 files changed

Lines changed: 686 additions & 63 deletions
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
'@hyperdx/app': patch
3+
'@hyperdx/common-utils': patch
4+
---
5+
6+
feat: Support background sparklines on PromQL range number tiles

‎packages/app/src/ChartUtils.tsx‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,11 @@ import {
99
JSDataType,
1010
ResponseJSON,
1111
} from '@hyperdx/common-utils/dist/clickhouse';
12+
import {
13+
DEFAULT_PROMQL_REDUCER,
14+
getQueriedPromqlSeries,
15+
isRangeQuery,
16+
} from '@hyperdx/common-utils/dist/core/promql';
1217
import { isMetricChartConfig } from '@hyperdx/common-utils/dist/core/renderChartConfig';
1318
import { SERIES_KEY_JOINER } from '@hyperdx/common-utils/dist/core/seriesNameTemplate';
1419
import {
@@ -28,10 +33,12 @@ import {
2833
BuilderSavedChartConfig,
2934
ChartConfigWithDateRange,
3035
ChartConfigWithOptDateRange,
36+
DateRange,
3137
DisplayType,
3238
Filter,
3339
isSearchableSource,
3440
MetricsDataType as MetricsDataTypeV2,
41+
PromqlChartConfig,
3542
SourceKind,
3643
SQLInterval,
3744
TMetricSource,
@@ -115,6 +122,41 @@ function getTimeChartDateRange(
115122

116123
export const MAX_TIME_CHART_SERIES = DEFAULT_SERIES_LIMIT;
117124

125+
/**
126+
* A PromQL number tile's queried config, shared by the value and the sparkline
127+
* drawn behind it.
128+
*/
129+
export function convertToPromqlNumberChartConfig(
130+
config: PromqlChartConfig & DateRange,
131+
{ withReducer }: { withReducer: boolean },
132+
): PromqlChartConfig & DateRange {
133+
const granularity = getTimeChartGranularity(
134+
config.granularity,
135+
config.dateRange,
136+
);
137+
return {
138+
...config,
139+
granularity,
140+
// Align the date range with the same buckets used by the sparkline and
141+
// timeseries charts, when using a (bucketed) range query. Alignment is
142+
// desirable for range queries to ensure consistent bucket boundaries
143+
// and sizes.
144+
dateRange: isRangeQuery(config)
145+
? getTimeChartDateRange(
146+
config.dateRange,
147+
config.alignDateRangeToGranularity,
148+
granularity,
149+
)
150+
: config.dateRange,
151+
promqlExpression: getQueriedPromqlSeries(config).map(series => ({
152+
...series,
153+
reducer: withReducer
154+
? (series.reducer ?? DEFAULT_PROMQL_REDUCER)
155+
: undefined,
156+
})),
157+
};
158+
}
159+
118160
export function convertToTimeChartConfig(
119161
config: ChartConfigWithDateRange,
120162
): ChartConfigWithDateRange {

‎packages/app/src/__tests__/ChartUtils.test.ts‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,16 @@
1+
import { DEFAULT_PROMQL_REDUCER } from '@hyperdx/common-utils/dist/core/promql';
12
import {
23
BuilderChartConfigWithDateRange,
4+
DisplayType,
5+
PromqlReducer,
36
SourceKind,
47
TSource,
58
} from '@hyperdx/common-utils/dist/types';
69

710
import {
811
ChartKeyJoiner,
912
convertToNumberChartConfig,
13+
convertToPromqlNumberChartConfig,
1014
convertToTableChartConfig,
1115
convertToTimeChartConfig,
1216
findNearestSeriesKey,
@@ -20,6 +24,7 @@ import {
2024
resolveRenderedSeriesCap,
2125
} from '@/defaults';
2226
import { COLORS } from '@/utils';
27+
import { stripClientSideConfigFields } from '@/utils/chartConfig';
2328

2429
// Anchor info/error to concrete hexes rather than `getChartColorInfo()` /
2530
// `getChartColorError()` so a regression that breaks the helpers can't
@@ -1279,6 +1284,124 @@ describe('ChartUtils', () => {
12791284
});
12801285
});
12811286

1287+
describe('convertToPromqlNumberChartConfig', () => {
1288+
const promqlConfig = {
1289+
configType: 'promql' as const,
1290+
displayType: DisplayType.Number,
1291+
connection: 'conn',
1292+
promqlExpression: [
1293+
{ expression: 'up', queryType: 'range' as const },
1294+
{ expression: 'down', queryType: 'range' as const },
1295+
],
1296+
dateRange: [
1297+
new Date('2025-11-26T00:00:14.076Z'),
1298+
new Date('2025-11-26T01:00:14.076Z'),
1299+
] as [Date, Date],
1300+
};
1301+
1302+
// Prometheus answers at `start + k * step`, so an unaligned start or an
1303+
// unresolved step puts the samples between the buckets the sparkline plots
1304+
// on -- which the empty-bucket filler then fills with zeros.
1305+
it('aligns the date range and resolves the granularity', () => {
1306+
const result = convertToPromqlNumberChartConfig(promqlConfig, {
1307+
withReducer: true,
1308+
});
1309+
1310+
expect(result.dateRange).toEqual([
1311+
new Date('2025-11-26T00:00:00Z'),
1312+
new Date('2025-11-26T01:01:00Z'),
1313+
]);
1314+
expect(result.granularity).toBe('1 minute');
1315+
});
1316+
1317+
it('leaves the date range unaligned for an instant query', () => {
1318+
const result = convertToPromqlNumberChartConfig(
1319+
{
1320+
...promqlConfig,
1321+
promqlExpression: [{ expression: 'up', queryType: 'instant' }],
1322+
dateRange: [
1323+
new Date('2025-11-26T00:00:14.076Z'),
1324+
new Date('2025-11-27T00:00:14.076Z'),
1325+
],
1326+
},
1327+
{ withReducer: true },
1328+
);
1329+
1330+
expect(result.dateRange).toEqual([
1331+
new Date('2025-11-26T00:00:14.076Z'),
1332+
new Date('2025-11-27T00:00:14.076Z'),
1333+
]);
1334+
expect(result.granularity).toBe('30 minute');
1335+
});
1336+
1337+
it('names the reducer, defaulting it, and queries one expression', () => {
1338+
const result = convertToPromqlNumberChartConfig(promqlConfig, {
1339+
withReducer: true,
1340+
});
1341+
1342+
expect(result).toEqual(
1343+
expect.objectContaining({
1344+
promqlExpression: [
1345+
{
1346+
expression: 'up',
1347+
queryType: 'range',
1348+
reducer: DEFAULT_PROMQL_REDUCER,
1349+
},
1350+
],
1351+
}),
1352+
);
1353+
});
1354+
1355+
it('keeps a chosen reducer', () => {
1356+
const result = convertToPromqlNumberChartConfig(
1357+
{
1358+
...promqlConfig,
1359+
promqlExpression: [
1360+
{
1361+
expression: 'up',
1362+
queryType: 'range' as const,
1363+
reducer: PromqlReducer.Max,
1364+
},
1365+
],
1366+
},
1367+
{ withReducer: true },
1368+
);
1369+
1370+
expect(result).toEqual(
1371+
expect.objectContaining({
1372+
promqlExpression: [
1373+
{
1374+
expression: 'up',
1375+
queryType: 'range',
1376+
reducer: PromqlReducer.Max,
1377+
},
1378+
],
1379+
}),
1380+
);
1381+
});
1382+
1383+
// Without a reducer named, the hook leaves the buckets alone -- which is
1384+
// how the sparkline reads the same response as the value.
1385+
it('names no reducer for the sparkline, otherwise matching the value', () => {
1386+
const value = convertToPromqlNumberChartConfig(promqlConfig, {
1387+
withReducer: true,
1388+
});
1389+
const sparkline = convertToPromqlNumberChartConfig(promqlConfig, {
1390+
withReducer: false,
1391+
});
1392+
1393+
expect(sparkline).toEqual({
1394+
...value,
1395+
promqlExpression: [
1396+
{ expression: 'up', queryType: 'range', reducer: undefined },
1397+
],
1398+
});
1399+
expect(stripClientSideConfigFields(sparkline)).toEqual(
1400+
stripClientSideConfigFields(value),
1401+
);
1402+
});
1403+
});
1404+
12821405
describe('convertToTableChartConfig', () => {
12831406
it('should remove granularity from the config', () => {
12841407
const config = {

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

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,18 +15,20 @@ const TYPE_OPTIONS = [
1515
* "Area" set the shape. The color swatch is an optional palette-token
1616
* override; when unset the sparkline inherits the tile's static color.
1717
*
18-
* `disabled` is set for raw SQL number tiles, which have no time dimension to
19-
* bucket: the control stays visible but inert with a hint, so the option is
20-
* discoverable rather than missing.
18+
* `disabled` is set where the tile's query has no buckets to plot -- raw SQL,
19+
* or a PromQL instant query. The control stays visible but inert with
20+
* `disabledHint` explaining which, so the option stays discoverable.
2121
*/
2222
export function BackgroundChartInput({
2323
value,
2424
onChange,
2525
disabled = false,
26+
disabledHint = 'Available on query-builder number tiles.',
2627
}: {
2728
value?: BackgroundChart;
2829
onChange: (value: BackgroundChart | undefined) => void;
2930
disabled?: boolean;
31+
disabledHint?: string;
3032
}) {
3133
return (
3234
<Box>
@@ -51,7 +53,7 @@ export function BackgroundChartInput({
5153
/>
5254
{disabled ? (
5355
<Text size="xs" c="dimmed" mt={4}>
54-
Available on query-builder number tiles.
56+
{disabledHint}
5557
</Text>
5658
) : (
5759
value && (

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

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,8 @@ interface ChartDisplaySettingsDrawerProps {
8080
displayType: DisplayType;
8181
/** 'sql' for raw SQL chart configs; anything else is treated as a builder config. */
8282
configType?: 'sql' | 'builder' | 'promql';
83+
/** Whether a PromQL tile's queried expression runs over a range. */
84+
promqlUsesRange?: boolean;
8385
previousDateRange?: [Date, Date];
8486
onChange: (settings: ChartConfigDisplaySettings, isDirty: boolean) => void;
8587
onClose: () => void;
@@ -119,6 +121,7 @@ export default function ChartDisplaySettingsDrawer({
119121
opened,
120122
displayType,
121123
configType,
124+
promqlUsesRange = false,
122125
defaultNumberFormat,
123126
onChange,
124127
onClose,
@@ -222,13 +225,19 @@ export default function ChartDisplaySettingsDrawer({
222225
// `select[i].color`.
223226
const showTileColor = displayType === DisplayType.Number;
224227

225-
// The background sparkline is derived from a time-bucketed version of the
226-
// tile's query, so it only applies to builder number tiles: raw SQL number
227-
// tiles return a single value with no time dimension to bucket. On a SQL
228-
// number tile the control is shown disabled with a hint rather than hidden,
229-
// so the option stays discoverable.
228+
// The sparkline needs buckets. A builder tile derives them from a
229+
// time-bucketed version of its query; a PromQL tile reuses the buckets its
230+
// range query fetches, so an instant one has none. Raw SQL returns a
231+
// single value with no time dimension at all. Where it cannot apply the
232+
// control is shown disabled with a hint rather than hidden, so the option
233+
// stays discoverable.
230234
const showBackgroundChart = displayType === DisplayType.Number;
231-
const isBackgroundChartDisabled = configType === 'sql';
235+
const isBackgroundChartDisabled =
236+
configType === 'sql' || (configType === 'promql' && !promqlUsesRange);
237+
const backgroundChartDisabledHint =
238+
configType === 'promql'
239+
? 'Available on PromQL range queries.'
240+
: 'Available on query-builder number tiles.';
232241

233242
return (
234243
<Drawer
@@ -430,6 +439,7 @@ export default function ChartDisplaySettingsDrawer({
430439
value={value}
431440
onChange={onChange}
432441
disabled={isBackgroundChartDisabled}
442+
disabledHint={backgroundChartDisabledHint}
433443
/>
434444
)}
435445
/>

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

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,19 @@ describe('convertFormStateToSavedChartConfig', () => {
129129
expect(result).toMatchObject({ alternateRowBackground: true });
130130
});
131131

132+
it('persists backgroundChart for a promql+number config', () => {
133+
const form: ChartEditorFormState = {
134+
configType: 'promql',
135+
displayType: DisplayType.Number,
136+
promqlExpression: 'up',
137+
connection: 'conn-1',
138+
backgroundChart: { type: 'area' },
139+
series: [],
140+
};
141+
const result = convertFormStateToSavedChartConfig(form, undefined);
142+
expect(result).toMatchObject({ backgroundChart: { type: 'area' } });
143+
});
144+
132145
it('persists alternateRowBackground for a promql+table config', () => {
133146
const form: ChartEditorFormState = {
134147
configType: 'promql',
@@ -409,6 +422,21 @@ describe('convertFormStateToChartConfig', () => {
409422
expect(result).toMatchObject({ alternateRowBackground: true });
410423
});
411424

425+
// The sparkline only renders if the rendered config carries this, and the
426+
// promql branch builds its config from an explicit pick list.
427+
it('threads backgroundChart into the rendered promql+number config', () => {
428+
const form: ChartEditorFormState = {
429+
configType: 'promql',
430+
displayType: DisplayType.Number,
431+
promqlExpression: 'up',
432+
connection: 'conn-1',
433+
backgroundChart: { type: 'area' },
434+
series: [],
435+
};
436+
const result = convertFormStateToChartConfig(form, dateRange, undefined);
437+
expect(result).toMatchObject({ backgroundChart: { type: 'area' } });
438+
});
439+
412440
it('threads alternateRowBackground into the rendered promql+table config', () => {
413441
const form: ChartEditorFormState = {
414442
configType: 'promql',

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -201,6 +201,7 @@ export function convertFormStateToSavedChartConfig(
201201
'numberFormat',
202202
'color',
203203
'colorRules',
204+
'backgroundChart',
204205
'granularity',
205206
'compareToPreviousPeriod',
206207
'fillNulls',
@@ -299,6 +300,7 @@ export function convertFormStateToChartConfig(
299300
'numberFormat',
300301
'color',
301302
'colorRules',
303+
'backgroundChart',
302304
'granularity',
303305
'compareToPreviousPeriod',
304306
'fillNulls',

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ import {
88
} from 'react-hook-form';
99
import { zodResolver } from '@hookform/resolvers/zod';
1010
import { tcFromSource } from '@hyperdx/common-utils/dist/core/metadata';
11+
import { isReducibleRangeQuery } from '@hyperdx/common-utils/dist/core/promql';
1112
import {
1213
displayTypeSupportsBuilderAlerts,
1314
displayTypeSupportsRawSqlAlerts,
@@ -267,6 +268,7 @@ export default function EditTimeChartForm({
267268
const markdown = useWatch({ control, name: 'markdown' });
268269
const granularity = useWatch({ control, name: 'granularity' });
269270
const configType = useWatch({ control, name: 'configType' });
271+
const promqlExpressions = useWatch({ control, name: 'promqlExpressions' });
270272

271273
const chartConfigAlert = chartConfig.alert;
272274
const isRawSqlInput =
@@ -1113,6 +1115,10 @@ export default function EditTimeChartForm({
11131115
previousDateRange={!dashboardId ? previousDateRange : undefined}
11141116
displayType={displayType}
11151117
configType={configType}
1118+
promqlUsesRange={isReducibleRangeQuery({
1119+
promqlExpression: promqlExpressions,
1120+
displayType,
1121+
})}
11161122
onChange={handleUpdateDisplaySettings}
11171123
onClose={closeDisplaySettings}
11181124
isPerSeriesNumberFormatAllowed={configType !== 'sql'}

0 commit comments

Comments
 (0)