Skip to content

Commit af688d2

Browse files
committed
feat: Support PromQL Macros
1 parent 78ed592 commit af688d2

21 files changed

Lines changed: 807 additions & 124 deletions

‎.changeset/promql-macros.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
'@hyperdx/common-utils': minor
3+
'@hyperdx/app': minor
4+
---
5+
6+
feat: Support macros in PromQL charts

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ export default function PromqlExpressionEditor({
6464
onSubmit={() => onSubmit()}
6565
placeholder="rate(http_requests_total{service='api'}[5m])"
6666
metricNames={metricNames}
67+
enableMacros
6768
/>
6869
</Box>
6970
{isIgnored ? (

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -415,7 +415,7 @@ describe('ChartPreviewPanel', () => {
415415
await userEvent.hover(wrapper!);
416416

417417
expect(
418-
await screen.findByText(/Variables could not be expanded/),
418+
await screen.findByText(/Expression could not be expanded/),
419419
).toBeInTheDocument();
420420
expect(
421421
screen.queryByTestId('chart-promql-preview'),

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

Lines changed: 43 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,7 @@ describe('buildRenderedPromqlExpression', () => {
222222
promqlExpression?: PromqlExpressionList;
223223
displayType?: DisplayType;
224224
variables?: ChartVariable[];
225+
granularity?: string;
225226
} = {},
226227
): ChartConfigWithDateRange => ({
227228
configType: 'promql',
@@ -302,6 +303,47 @@ describe('buildRenderedPromqlExpression', () => {
302303
).toEqual(['up{service=~"api"}', 'errors{service=~"api"}']);
303304
});
304305

306+
it('expands macros with the granularity the chart queries with', () => {
307+
const expression = 'rate(up[$__rate_interval]) / $__interval / $__range';
308+
const render = (displayType: DisplayType, granularity?: string) =>
309+
buildRenderedPromqlExpression(
310+
promqlConfig({
311+
displayType,
312+
granularity,
313+
promqlExpression: [{ expression }],
314+
}),
315+
)?.expressions?.[0].expression;
316+
317+
expect(render(DisplayType.Line, '5 minute')).toBe(
318+
'rate(up[315s]) / 300s / 86400s',
319+
);
320+
// `auto` resolves to the chart's 80-bucket granularity (30 minutes for a
321+
// day), not promqlStep's own fallback.
322+
expect(render(DisplayType.Line, 'auto')).toBe(
323+
'rate(up[1815s]) / 1800s / 86400s',
324+
);
325+
expect(render(DisplayType.Number, 'auto')).toBe(
326+
'rate(up[1815s]) / 1800s / 86400s',
327+
);
328+
});
329+
330+
it('expands macros with the granularity a table queries with', () => {
331+
const seventyMinutes: [Date, Date] = [
332+
new Date('2024-01-01T00:00:00Z'),
333+
new Date('2024-01-01T01:10:00Z'),
334+
];
335+
expect(
336+
buildRenderedPromqlExpression({
337+
...promqlConfig({
338+
displayType: DisplayType.Table,
339+
granularity: 'auto',
340+
promqlExpression: [{ expression: 'rate(up[$__interval])' }],
341+
}),
342+
dateRange: seventyMinutes,
343+
})?.expressions?.[0].expression,
344+
).toBe('rate(up[60s])');
345+
});
346+
305347
it('reports a substitution failure instead of an expression', () => {
306348
const result = buildRenderedPromqlExpression(
307349
promqlConfig({
@@ -310,7 +352,7 @@ describe('buildRenderedPromqlExpression', () => {
310352
}),
311353
);
312354
expect(result?.expressions).toBeUndefined();
313-
expect(result?.error).toMatch(/Variables could not be expanded/);
355+
expect(result?.error).toMatch(/Expression could not be expanded/);
314356
});
315357
});
316358

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

Lines changed: 34 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import {
44
TableConnectionChoice,
55
} from '@hyperdx/common-utils/dist/core/metadata';
66
import { getQueriedPromqlSeries } from '@hyperdx/common-utils/dist/core/promql';
7+
import { isTimeSeriesDisplayType } from '@hyperdx/common-utils/dist/core/utils';
78
import {
89
configConsumesBroadcastFilters,
910
getBlockingRequiredFilterNames,
@@ -14,29 +15,31 @@ import {
1415
isRawSqlChartConfig,
1516
isRawSqlSavedChartConfig,
1617
} from '@hyperdx/common-utils/dist/guards';
18+
import { substitutePromqlChartConfigTemplates } from '@hyperdx/common-utils/dist/macros';
1719
import {
1820
BuilderChartConfigWithDateRange,
1921
ChartAlertBaseSchema,
2022
ChartConfigWithDateRange,
2123
ChartConfigWithOptTimestamp,
2224
ChartVariable,
2325
DashboardFilter,
26+
DateRange,
2427
DisplayType,
2528
Filter,
29+
PromqlChartConfig,
2630
SavedChartConfig,
2731
SelectList,
2832
SourceKind,
2933
TSource,
3034
validateAlertScheduleOffsetMinutes,
3135
} from '@hyperdx/common-utils/dist/types';
32-
import {
33-
filterReferencedVariables,
34-
substitutePromqlChartConfigVariables,
35-
} from '@hyperdx/common-utils/dist/variables';
36+
import { filterReferencedVariables } from '@hyperdx/common-utils/dist/variables';
3637

3738
import {
3839
convertToCategoricalChartConfig,
3940
convertToNumberChartConfig,
41+
convertToPromqlNumberChartConfig,
42+
convertToPromqlTableChartConfig,
4043
convertToTableChartConfig,
4144
convertToTimeChartConfig,
4245
tryExpandConfigVariables,
@@ -263,7 +266,28 @@ export type RenderedPromqlExpression =
263266
| { expressions: RenderedPromqlEntry[]; error?: never }
264267
| { expressions?: never; error: string };
265268

266-
/** The expressions a PromQL tile is queried with, with variables substituted. */
269+
/**
270+
* The config a PromQL chart of this display type actually queries with. Macros
271+
* depend on the resolved granularity and date range, so the preview must
272+
* resolve them the same way the chart does.
273+
*/
274+
function toQueriedPromqlConfig(
275+
config: PromqlChartConfig & DateRange,
276+
): PromqlChartConfig & DateRange {
277+
if (config.displayType === DisplayType.Number) {
278+
return convertToPromqlNumberChartConfig(config, { withReducer: false });
279+
}
280+
if (config.displayType === DisplayType.Table) {
281+
return convertToPromqlTableChartConfig(config);
282+
}
283+
if (isTimeSeriesDisplayType(config.displayType)) {
284+
const converted = convertToTimeChartConfig(config);
285+
return isPromqlChartConfig(converted) ? converted : config;
286+
}
287+
return config;
288+
}
289+
290+
/** The expressions a PromQL tile is queried with, with macros and variables substituted. */
267291
export function buildRenderedPromqlExpression(
268292
queriedConfig: ChartConfigWithDateRange | undefined,
269293
): RenderedPromqlExpression | undefined {
@@ -272,7 +296,9 @@ export function buildRenderedPromqlExpression(
272296
}
273297

274298
try {
275-
const substituted = substitutePromqlChartConfigVariables(queriedConfig);
299+
const substituted = substitutePromqlChartConfigTemplates(
300+
toQueriedPromqlConfig(queriedConfig),
301+
);
276302
return {
277303
expressions: getQueriedPromqlSeries(substituted).map((series, index) => ({
278304
id: String(index),
@@ -287,8 +313,8 @@ export function buildRenderedPromqlExpression(
287313
return {
288314
error:
289315
e instanceof Error
290-
? `Variables could not be expanded: ${e.message}`
291-
: 'Variables could not be expanded.',
316+
? `Expression could not be expanded: ${e.message}`
317+
: 'Expression could not be expanded.',
292318
};
293319
}
294320
}

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

Lines changed: 26 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -23,13 +23,17 @@ import {
2323
createCodeMirrorStyleTheme,
2424
DEFAULT_CODE_MIRROR_BASIC_SETUP,
2525
} from '@/components/SQLEditor/utils';
26-
import { usePromqlVariableCompletions } from '@/components/SQLEditor/variableCompletions';
26+
import {
27+
PROMQL_MACRO_COMPLETIONS,
28+
usePromqlVariableCompletions,
29+
} from '@/components/SQLEditor/variableCompletions';
2730
import {
2831
useVariableValidation,
2932
VariableIssueIndicator,
3033
variableValidationState,
3134
} from '@/components/SQLEditor/variableValidation';
3235

36+
import { promqlTemplateExtension } from './templateMaskedLanguage';
3337
import { createVariableCompletionSource } from './variableCompletionSource';
3438

3539
import styles from '@/components/SQLEditor/SQLInlineEditor.module.scss';
@@ -47,6 +51,8 @@ type PromQLEditorProps = {
4751
* modal or other scroll container, which would otherwise clip the popup.
4852
*/
4953
parentRef?: HTMLElement | null;
54+
/** Suggest `$__interval` and the other chart macros. */
55+
enableMacros?: boolean;
5056
};
5157

5258
const MAX_EDITOR_HEIGHT = '150px';
@@ -113,30 +119,37 @@ export default function PromQLEditor({
113119
onSubmit,
114120
metricNames,
115121
parentRef,
122+
enableMacros,
116123
}: PromQLEditorProps) {
117124
const { colorScheme } = useMantineColorScheme();
118125
const ref = useRef<ReactCodeMirrorRef>(null);
119126
const compartmentRef = useRef<Compartment>(new Compartment());
120127
const [isFocused, setIsFocused] = useState(false);
121128
const variableCompletions = usePromqlVariableCompletions();
129+
const templateCompletions = useMemo(
130+
() =>
131+
enableMacros
132+
? [...PROMQL_MACRO_COMPLETIONS, ...variableCompletions]
133+
: variableCompletions,
134+
[enableMacros, variableCompletions],
135+
);
122136
const variableIssues = useVariableValidation(value, { language: 'promql' });
123137

124138
const updateAutocomplete = useCallback(
125139
(viewRef: EditorView) => {
126140
const override: CompletionSource[] = [];
127141

128-
if (variableCompletions.length > 0) {
129-
override.push(createVariableCompletionSource(variableCompletions));
142+
if (templateCompletions.length > 0) {
143+
override.push(createVariableCompletionSource(templateCompletions));
130144
}
131145

132146
if (metricNames?.length) {
133147
override.push(debounceAndPruneAutocompleteResults(metricNames));
134148
}
135149

136-
// PromQL's own function/keyword completion, re-registered explicitly.
137-
// `PromQLExtension.asExtension()` registers it through
138-
// `language.data.of({ autocomplete })`, which an `override` array
139-
// replaces outright — so without this it is silently lost.
150+
// PromQL's own function/keyword completion. `promqlTemplateExtension`
151+
// installs the language without it, and an `override` array would
152+
// replace a `language.data` registration outright anyway.
140153
override.push(context => promqlExtension.getComplete().promQL(context));
141154

142155
viewRef.dispatch({
@@ -145,7 +158,7 @@ export default function PromQLEditor({
145158
),
146159
});
147160
},
148-
[metricNames, variableCompletions],
161+
[metricNames, templateCompletions],
149162
);
150163

151164
useEffect(() => {
@@ -160,8 +173,10 @@ export default function PromQLEditor({
160173
createCodeMirrorStyleTheme(MAX_EDITOR_HEIGHT),
161174
EditorView.lineWrapping,
162175

163-
// PromQL syntax highlighting
164-
promqlExtension.asExtension(),
176+
// PromQL syntax highlighting and linting, variable- and macro-aware
177+
promqlTemplateExtension(promqlExtension, {
178+
enableMacros: !!enableMacros,
179+
}),
165180

166181
// Autocomplete sources (via compartment for hot-swapping)
167182
// eslint-disable-next-line react-hooks/refs
@@ -190,7 +205,7 @@ export default function PromQLEditor({
190205
},
191206
]),
192207
],
193-
[onSubmit, parentRef],
208+
[onSubmit, parentRef, enableMacros],
194209
);
195210

196211
const onClickCodeMirror = useCallback(() => {
Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
import {
2+
findMaskedTemplateRanges,
3+
maskPromqlTemplates,
4+
templateMaskedPromqlLanguage,
5+
} from '@/components/PromQLEditor/templateMaskedLanguage';
6+
7+
const errorSpans = (doc: string, enableMacros = true) => {
8+
const spans: string[] = [];
9+
templateMaskedPromqlLanguage({ enableMacros })
10+
.parser.parse(doc)
11+
.iterate({
12+
enter: node => {
13+
if (node.type.isError) spans.push(doc.slice(node.from, node.to));
14+
},
15+
});
16+
return spans;
17+
};
18+
19+
describe('findMaskedTemplateRanges', () => {
20+
it('covers each macro and reference exactly', () => {
21+
const expression = 'topk($k, rate(up[$__rate_interval]))';
22+
expect(
23+
findMaskedTemplateRanges(expression, { enableMacros: true }).map(
24+
({ from, to }) => expression.slice(from, to),
25+
),
26+
).toEqual(['$k', '$__rate_interval']);
27+
});
28+
29+
it('leaves references inside label strings alone', () => {
30+
expect(
31+
findMaskedTemplateRanges('up{service=~"$service"}', {
32+
enableMacros: true,
33+
}),
34+
).toEqual([]);
35+
});
36+
});
37+
38+
describe('maskPromqlTemplates', () => {
39+
it('keeps the expression length', () => {
40+
const expression = 'rate(up{a="$a"}[$__interval]) * $k';
41+
const masked = maskPromqlTemplates(expression, { enableMacros: true });
42+
expect(masked).toBe('rate(up{a="$a"}[11111111111]) * aa');
43+
expect(masked).toHaveLength(expression.length);
44+
});
45+
46+
it('masks a variable in a label-name position as an identifier', () => {
47+
expect(
48+
maskPromqlTemplates('sum by (${service:csv}) (up)', {
49+
enableMacros: true,
50+
}),
51+
).toBe('sum by (aaaaaaaaaaaaaa) (up)');
52+
});
53+
});
54+
55+
describe('templateMaskedPromqlLanguage', () => {
56+
it('parses macros in range and offset positions', () => {
57+
expect(
58+
errorSpans(
59+
'sum(rate(up[$__range])) + avg_over_time(up[$__interval] offset $__rate_interval)',
60+
),
61+
).toEqual([]);
62+
});
63+
64+
it('parses variables in metric and label name positions', () => {
65+
expect(errorSpans('sum by (${service:csv}) (up)')).toEqual([]);
66+
expect(errorSpans('sum by (job, $label) ($metric{${key}="x"})')).toEqual(
67+
[],
68+
);
69+
expect(errorSpans('a / on(${keys:csv}) group_left($extra) b')).toEqual([]);
70+
});
71+
72+
it('rejects a variable in a duration position', () => {
73+
expect(errorSpans('rate(up[$window])')).not.toEqual([]);
74+
});
75+
76+
it('keeps node offsets on the original text', () => {
77+
const doc = 'rate(up[$__range])';
78+
const spans: string[] = [];
79+
templateMaskedPromqlLanguage({ enableMacros: true })
80+
.parser.parse(doc)
81+
.iterate({
82+
enter: node => {
83+
if (node.name === 'NumberDurationLiteralInDurationContext') {
84+
spans.push(doc.slice(node.from, node.to));
85+
}
86+
},
87+
});
88+
expect(spans).toEqual(['$__range']);
89+
});
90+
91+
it('rejects macros when macros are disabled', () => {
92+
expect(errorSpans('rate(up[$__interval])', false)).not.toEqual([]);
93+
});
94+
95+
it('parses a macro given arguments', () => {
96+
expect(errorSpans('rate(up[$__interval(1)])')).toEqual([]);
97+
});
98+
99+
it('still rejects errors elsewhere in the expression', () => {
100+
expect(errorSpans('rate(up[$__interval]) +')).not.toEqual([]);
101+
});
102+
});

0 commit comments

Comments
 (0)