Skip to content

Commit 431e3eb

Browse files
committed
feat: Add promql var format for flexible escaping
1 parent acfcd09 commit 431e3eb

15 files changed

Lines changed: 326 additions & 71 deletions

File tree

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
'@hyperdx/common-utils': patch
3+
'@hyperdx/api': patch
4+
'@hyperdx/app': patch
5+
---
6+
7+
feat: Add a promql variable format that escapes based on single/multi-select

‎packages/api/src/mcp/prompts/dashboards/content.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1222,6 +1222,7 @@ Only add one when the default is wrong. \${service:sqlstring} is redundant in a
12221222
sqlstring 'a', 'b' NULL the default in SQL inputs
12231223
lucene ("a" OR "b") ("") the default in Lucene inputs; ("") is a match-all, so no guard is needed
12241224
regex (a|b) .* use with match()
1225+
promql a or (a|b) "" or .* the default in PromQL; a single-select variable (maxSelections: 1) renders its raw value for {label="$var"}, a multi-select one an escaped regex for {label=~"$var"}
12251226
csv a,b <empty> use INSIDE a string literal
12261227
markdown a, b <empty> the default in markdown tiles; markdown syntax in values is escaped
12271228

‎packages/api/src/mcp/tools/dashboards/schemas.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1255,7 +1255,10 @@ const mcpDashboardFilterBaseShape = {
12551255
.optional()
12561256
.describe(
12571257
'Set to 1 to make this filter SINGLE-SELECT: the user can pick at most one ' +
1258-
'value. Omit for the normal multi-select behavior.',
1258+
'value. In PromQL, a single-select variable expands to its raw value by ' +
1259+
'default (for exact matchers such as {job="$job"}), while a multi-select ' +
1260+
'one expands to an escaped regex (for {job=~"$job"}). Omit for the normal ' +
1261+
'multi-select behavior.',
12591262
),
12601263
};
12611264

‎packages/api/src/mcp/tools/dashboards/variables.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,11 @@ import {
22
getDashboardVariableDeclarations,
33
getDashboardVariableFilters,
44
getFilterVariableName,
5-
isFilterSingleSelect,
65
isFilterVariableEnabled,
76
isStaticListFilter,
87
} from '@hyperdx/common-utils/dist/filters';
98
import type { ChartVariable } from '@hyperdx/common-utils/dist/types';
9+
import { isFilterSingleSelect } from '@hyperdx/common-utils/dist/variables';
1010
import { z } from 'zod';
1111

1212
import type {

‎packages/app/src/DashboardFilters.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@ import {
66
getPendingFilterValuesVariables,
77
isFilterGlobalRequirement,
88
isFilterRequired,
9-
isFilterSingleSelect,
109
isFilterVariableEnabled,
1110
isQueryExpressionFilter,
1211
isStaticListFilter,
@@ -15,6 +14,7 @@ import {
1514
ChartVariable,
1615
DashboardFilter,
1716
} from '@hyperdx/common-utils/dist/types';
17+
import { isFilterSingleSelect } from '@hyperdx/common-utils/dist/variables';
1818
import { Group, Stack, Text, Tooltip } from '@mantine/core';
1919
import { IconAlertTriangle, IconHelp, IconRefresh } from '@tabler/icons-react';
2020

‎packages/app/src/components/DashboardFiltersModal/filterFormState.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@ import {
44
isFilterBroadcastEnabled,
55
isFilterGlobalRequirement,
66
isFilterRequired,
7-
isFilterSingleSelect,
87
isFilterVariableEnabled,
98
} from '@hyperdx/common-utils/dist/filters';
109
import {
@@ -14,6 +13,7 @@ import {
1413
QueryExpressionDashboardFilter,
1514
StaticListDashboardFilter,
1615
} from '@hyperdx/common-utils/dist/types';
16+
import { isFilterSingleSelect } from '@hyperdx/common-utils/dist/variables';
1717

1818
import { getStoredLanguage } from '@/components/SearchInput/SearchWhereInput';
1919

‎packages/app/src/components/SQLEditor/__tests__/promqlVariableCompletions.test.ts‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ describe('buildPromqlVariableCompletions', () => {
5050
expect(labels([SERVICE])).toEqual([
5151
'$service',
5252
'${service}',
53+
'${service:promql}',
5354
'${service:regex}',
5455
'${service:csv}',
5556
]);
@@ -80,10 +81,12 @@ describe('buildPromqlVariableCompletions', () => {
8081
expect(labels([SERVICE, { name: 'env', values: ['prod'] }])).toEqual([
8182
'$service',
8283
'${service}',
84+
'${service:promql}',
8385
'${service:regex}',
8486
'${service:csv}',
8587
'$env',
8688
'${env}',
89+
'${env:promql}',
8790
'${env:regex}',
8891
'${env:csv}',
8992
]);
@@ -92,14 +95,15 @@ describe('buildPromqlVariableCompletions', () => {
9295
it.each([
9396
['$service', 'Expands to: (api|web)'],
9497
['${service}', 'Expands to: (api|web)'],
98+
['${service:promql}', 'Expands to: (api|web)'],
9599
['${service:regex}', 'Expands to: (api|web)'],
96100
['${service:csv}', 'Expands to: api,web'],
97101
])('shows what %s expands to under promql, not sql', (label, expected) => {
98102
expect(footnoteOf([SERVICE], label)).toBe(expected);
99103
});
100104

101105
it('previews the empty selection as the match-everything regex', () => {
102-
// The reason the regex format is PromQL's default: with nothing selected a
106+
// The reason a multi-select variable defaults to a regex in PromQL: with nothing selected a
103107
// `=~` matcher still matches, rather than becoming NULL as it would in SQL.
104108
const unselected: ChartVariable = { ...SERVICE, values: [] };
105109
expect(footnoteOf([unselected], '$service')).toBe('Expands to: .*');
@@ -109,6 +113,33 @@ describe('buildPromqlVariableCompletions', () => {
109113
);
110114
});
111115

116+
describe('for a single-select variable', () => {
117+
const singleSelect: ChartVariable = {
118+
...SERVICE,
119+
values: ['v1.2'],
120+
maxSelections: 1,
121+
};
122+
123+
it('describes $name as an exact-match value', () => {
124+
const info = infoOf([singleSelect], '$service');
125+
if (typeof info !== 'object') throw new Error('expected rendered markup');
126+
expect(info?.firstChild?.textContent).toContain('{label="$service"}');
127+
});
128+
129+
it('previews the default as the unescaped value and regex as escaped', () => {
130+
expect(footnoteOf([singleSelect], '$service')).toBe('Expands to: v1.2');
131+
expect(footnoteOf([singleSelect], '${service:regex}')).toBe(
132+
'Expands to: v1\\\\.2',
133+
);
134+
});
135+
136+
it('previews the empty selection as an empty string', () => {
137+
expect(footnoteOf([{ ...singleSelect, values: [] }], '$service')).toBe(
138+
'Expands to: (empty string)',
139+
);
140+
});
141+
});
142+
112143
it('puts the expansion on its own line, not appended to the prose', () => {
113144
const info = infoOf([SERVICE], '$service');
114145
if (typeof info !== 'object') throw new Error('expected rendered markup');

‎packages/app/src/components/SQLEditor/__tests__/variableCompletions.test.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,8 +53,9 @@ describe('buildSqlVariableCompletions', () => {
5353
);
5454
});
5555

56-
it('withholds the markdown format, which only applies to markdown tiles', () => {
56+
it('withholds the markdown and promql formats, which only apply elsewhere', () => {
5757
expect(labels([SERVICE])).not.toContain('${service:markdown}');
58+
expect(labels([SERVICE])).not.toContain('${service:promql}');
5859
});
5960

6061
it('withholds the macros that a chart builder input never expands', () => {

‎packages/app/src/components/SQLEditor/variableCompletions.tsx‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import {
66
} from '@hyperdx/common-utils/dist/macros';
77
import { ChartVariable } from '@hyperdx/common-utils/dist/types';
88
import {
9+
isFilterSingleSelect,
910
substituteVariables,
1011
TemplateLanguage,
1112
VariableFormat,
@@ -30,8 +31,10 @@ const COMPLETION_FORMATS: Record<
3031
'An OR of quoted terms, for Lucene inputs. e.g. ("a" OR "b" OR "c"). Quote the reference (field:"$var") for exact-match behavior. Leave unquoted (field:$var) for substring matching.',
3132
},
3233
promql: {
34+
promql:
35+
'The default format, written out. A single-select variable renders its value as written, for {label="$var"}; a multi-select variable renders a regex alternation, for {label=~"$var"}. Escaped for the double-quoted string literal it sits in.',
3336
regex:
34-
'The default format, written out. A regex alternation, escaped for the string literal it sits in. e.g. (a|b|c)',
37+
'A regex alternation, always regex escaped, and escaped for the double-quoted string literal it sits in. e.g. (a|b|c)',
3538
csv: 'Comma-separated and unquoted, with no escaping.',
3639
},
3740
// Lucene inputs suggest only the bare `$name` reference.
@@ -186,7 +189,9 @@ function getPromqlVariableCompletions(
186189
return [
187190
reference(
188191
`$${name}`,
189-
`The selected values of ${name} as a regex alternation, for use inside a matcher such as {label=~"$${name}"}. Matches everything when nothing is selected.`,
192+
isFilterSingleSelect(variable)
193+
? `The selected value of ${name} as written, for use inside an exact matcher such as {label="$${name}"}. An empty string when nothing is selected.`
194+
: `The selected values of ${name} as a regex alternation, for use inside a matcher such as {label=~"$${name}"}. Matches everything when nothing is selected.`,
190195
),
191196
reference(
192197
`\${${name}}`,

‎packages/app/tests/e2e/features/dashboard-filter-variables.spec.ts‎

Lines changed: 54 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -375,6 +375,56 @@ test.describe(
375375
});
376376
});
377377

378+
test('matches a single-select variable exactly', async ({ page }) => {
379+
test.setTimeout(120000);
380+
381+
const dashboardPage = new DashboardPage(page);
382+
const seriesAreas = page
383+
.locator('.recharts-responsive-container')
384+
.first()
385+
.locator('.recharts-area');
386+
387+
await test.step('Create a dashboard with a single-select $svc variable', async () => {
388+
await dashboardPage.goto();
389+
await dashboardPage.createNewDashboard();
390+
await dashboardPage.openEditFiltersModal();
391+
await dashboardPage.addStaticListFilterToDashboard(
392+
'Service',
393+
SERVICES.slice(0, 2),
394+
{ variableName: 'svc', singleSelect: true },
395+
);
396+
await dashboardPage.closeFiltersModal();
397+
});
398+
399+
await test.step('Add a PromQL tile with an exact $svc matcher', async () => {
400+
await openPromqlTileEditor(dashboardPage);
401+
await dashboardPage.chartEditor.setChartName('PromQL tile');
402+
await dashboardPage.chartEditor.replacePromqlExpression(
403+
`${E2E_PROMQL_METRIC_NAME}{service="$svc"}`,
404+
);
405+
await dashboardPage.chartEditor.save();
406+
await expect(dashboardPage.getTiles()).toHaveCount(1, {
407+
timeout: 10000,
408+
});
409+
});
410+
411+
await test.step('With nothing selected, no series match', async () => {
412+
// A zero series count also holds while the tile is still loading.
413+
await expect(
414+
dashboardPage
415+
.getTiles()
416+
.first()
417+
.getByText('No data found within time range.'),
418+
).toBeVisible({ timeout: 30000 });
419+
await expect(seriesAreas).toHaveCount(0);
420+
});
421+
422+
await test.step('Selecting a service matches its series', async () => {
423+
await dashboardPage.toggleFilterValue('Service', SERVICES[0]);
424+
await expect(seriesAreas).toHaveCount(1, { timeout: 30000 });
425+
});
426+
});
427+
378428
/**
379429
* The expression above is only writable if the editor tells you the
380430
* variable exists. Three completion sources share the PromQL input —
@@ -417,9 +467,10 @@ test.describe(
417467
const info = page.locator('.cm-completionInfo');
418468
await info.waitFor({ state: 'visible', timeout: 10000 });
419469

420-
// Nothing is selected on this dashboard, and regex is promql's default
421-
// format — so the bare reference previews the match-everything state
422-
// that makes the tile above valid before anything is picked.
470+
// Nothing is selected on this dashboard, and a multi-select variable
471+
// renders as a regex by default — so the bare reference previews the
472+
// match-everything state that makes the tile above valid before
473+
// anything is picked.
423474
await expect(info.locator('.cm-completionInfo-footnote')).toHaveText(
424475
'Expands to: .*',
425476
);

0 commit comments

Comments
 (0)