diff --git a/.changeset/promql-variable-format.md b/.changeset/promql-variable-format.md new file mode 100644 index 0000000000..a11479ad5b --- /dev/null +++ b/.changeset/promql-variable-format.md @@ -0,0 +1,7 @@ +--- +'@hyperdx/common-utils': patch +'@hyperdx/api': patch +'@hyperdx/app': patch +--- + +feat: Add a promql variable format that escapes based on single/multi-select diff --git a/packages/api/src/mcp/prompts/dashboards/content.ts b/packages/api/src/mcp/prompts/dashboards/content.ts index 934902e8d3..69c8f4eb17 100644 --- a/packages/api/src/mcp/prompts/dashboards/content.ts +++ b/packages/api/src/mcp/prompts/dashboards/content.ts @@ -1224,6 +1224,7 @@ Only add one when the default is wrong. \${service:sqlstring} is redundant in a sqlstring 'a', 'b' NULL the default in SQL inputs lucene ("a" OR "b") ("") the default in Lucene inputs; ("") is a match-all, so no guard is needed regex (a|b) .* use with match() + 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"} csv a,b use INSIDE a string literal markdown a, b the default in markdown tiles; markdown syntax in values is escaped diff --git a/packages/api/src/mcp/tools/dashboards/schemas.ts b/packages/api/src/mcp/tools/dashboards/schemas.ts index 02522a2bcd..afacdf390f 100644 --- a/packages/api/src/mcp/tools/dashboards/schemas.ts +++ b/packages/api/src/mcp/tools/dashboards/schemas.ts @@ -1327,7 +1327,10 @@ const mcpDashboardFilterBaseShape = { .optional() .describe( 'Set to 1 to make this filter SINGLE-SELECT: the user can pick at most one ' + - 'value. Omit for the normal multi-select behavior.', + 'value. In PromQL, a single-select variable expands to its raw value by ' + + 'default (for exact matchers such as {job="$job"}), while a multi-select ' + + 'one expands to an escaped regex (for {job=~"$job"}). Omit for the normal ' + + 'multi-select behavior.', ), }; diff --git a/packages/api/src/mcp/tools/dashboards/variables.ts b/packages/api/src/mcp/tools/dashboards/variables.ts index 64a6a1678d..f1b98a6116 100644 --- a/packages/api/src/mcp/tools/dashboards/variables.ts +++ b/packages/api/src/mcp/tools/dashboards/variables.ts @@ -2,11 +2,11 @@ import { getDashboardVariableDeclarations, getDashboardVariableFilters, getFilterVariableName, - isFilterSingleSelect, isFilterVariableEnabled, isStaticListFilter, } from '@hyperdx/common-utils/dist/filters'; import type { ChartVariable } from '@hyperdx/common-utils/dist/types'; +import { isFilterSingleSelect } from '@hyperdx/common-utils/dist/variables'; import { z } from 'zod'; import type { diff --git a/packages/app/src/DashboardFilters.tsx b/packages/app/src/DashboardFilters.tsx index 9242b71e61..9915d1154c 100644 --- a/packages/app/src/DashboardFilters.tsx +++ b/packages/app/src/DashboardFilters.tsx @@ -6,7 +6,6 @@ import { getPendingFilterValuesVariables, isFilterGlobalRequirement, isFilterRequired, - isFilterSingleSelect, isFilterVariableEnabled, isQueryExpressionFilter, isStaticListFilter, @@ -15,6 +14,7 @@ import { ChartVariable, DashboardFilter, } from '@hyperdx/common-utils/dist/types'; +import { isFilterSingleSelect } from '@hyperdx/common-utils/dist/variables'; import { Group, Stack, Text, Tooltip } from '@mantine/core'; import { IconAlertTriangle, IconHelp, IconRefresh } from '@tabler/icons-react'; diff --git a/packages/app/src/components/DashboardFiltersModal/filterFormState.ts b/packages/app/src/components/DashboardFiltersModal/filterFormState.ts index 94da455c08..2dac17acd0 100644 --- a/packages/app/src/components/DashboardFiltersModal/filterFormState.ts +++ b/packages/app/src/components/DashboardFiltersModal/filterFormState.ts @@ -4,7 +4,6 @@ import { isFilterBroadcastEnabled, isFilterGlobalRequirement, isFilterRequired, - isFilterSingleSelect, isFilterVariableEnabled, } from '@hyperdx/common-utils/dist/filters'; import { @@ -14,6 +13,7 @@ import { QueryExpressionDashboardFilter, StaticListDashboardFilter, } from '@hyperdx/common-utils/dist/types'; +import { isFilterSingleSelect } from '@hyperdx/common-utils/dist/variables'; import { getStoredLanguage } from '@/components/SearchInput/SearchWhereInput'; diff --git a/packages/app/src/components/SQLEditor/__tests__/promqlVariableCompletions.test.ts b/packages/app/src/components/SQLEditor/__tests__/promqlVariableCompletions.test.ts index fbb3fbfdb7..49bd6b008a 100644 --- a/packages/app/src/components/SQLEditor/__tests__/promqlVariableCompletions.test.ts +++ b/packages/app/src/components/SQLEditor/__tests__/promqlVariableCompletions.test.ts @@ -50,6 +50,7 @@ describe('buildPromqlVariableCompletions', () => { expect(labels([SERVICE])).toEqual([ '$service', '${service}', + '${service:promql}', '${service:regex}', '${service:csv}', ]); @@ -80,10 +81,12 @@ describe('buildPromqlVariableCompletions', () => { expect(labels([SERVICE, { name: 'env', values: ['prod'] }])).toEqual([ '$service', '${service}', + '${service:promql}', '${service:regex}', '${service:csv}', '$env', '${env}', + '${env:promql}', '${env:regex}', '${env:csv}', ]); @@ -92,6 +95,7 @@ describe('buildPromqlVariableCompletions', () => { it.each([ ['$service', 'Expands to: (api|web)'], ['${service}', 'Expands to: (api|web)'], + ['${service:promql}', 'Expands to: (api|web)'], ['${service:regex}', 'Expands to: (api|web)'], ['${service:csv}', 'Expands to: api,web'], ])('shows what %s expands to under promql, not sql', (label, expected) => { @@ -99,7 +103,7 @@ describe('buildPromqlVariableCompletions', () => { }); it('previews the empty selection as the match-everything regex', () => { - // The reason the regex format is PromQL's default: with nothing selected a + // The reason a multi-select variable defaults to a regex in PromQL: with nothing selected a // `=~` matcher still matches, rather than becoming NULL as it would in SQL. const unselected: ChartVariable = { ...SERVICE, values: [] }; expect(footnoteOf([unselected], '$service')).toBe('Expands to: .*'); @@ -109,6 +113,33 @@ describe('buildPromqlVariableCompletions', () => { ); }); + describe('for a single-select variable', () => { + const singleSelect: ChartVariable = { + ...SERVICE, + values: ['v1.2'], + maxSelections: 1, + }; + + it('describes $name as an exact-match value', () => { + const info = infoOf([singleSelect], '$service'); + if (typeof info !== 'object') throw new Error('expected rendered markup'); + expect(info?.firstChild?.textContent).toContain('{label="$service"}'); + }); + + it('previews the default as the unescaped value and regex as escaped', () => { + expect(footnoteOf([singleSelect], '$service')).toBe('Expands to: v1.2'); + expect(footnoteOf([singleSelect], '${service:regex}')).toBe( + 'Expands to: v1\\\\.2', + ); + }); + + it('previews the empty selection as an empty string', () => { + expect(footnoteOf([{ ...singleSelect, values: [] }], '$service')).toBe( + 'Expands to: (empty string)', + ); + }); + }); + it('puts the expansion on its own line, not appended to the prose', () => { const info = infoOf([SERVICE], '$service'); if (typeof info !== 'object') throw new Error('expected rendered markup'); diff --git a/packages/app/src/components/SQLEditor/__tests__/variableCompletions.test.ts b/packages/app/src/components/SQLEditor/__tests__/variableCompletions.test.ts index eac445c96a..31b91cbcc8 100644 --- a/packages/app/src/components/SQLEditor/__tests__/variableCompletions.test.ts +++ b/packages/app/src/components/SQLEditor/__tests__/variableCompletions.test.ts @@ -53,8 +53,9 @@ describe('buildSqlVariableCompletions', () => { ); }); - it('withholds the markdown format, which only applies to markdown tiles', () => { + it('withholds the markdown and promql formats, which only apply elsewhere', () => { expect(labels([SERVICE])).not.toContain('${service:markdown}'); + expect(labels([SERVICE])).not.toContain('${service:promql}'); }); it('withholds the macros that a chart builder input never expands', () => { diff --git a/packages/app/src/components/SQLEditor/variableCompletions.tsx b/packages/app/src/components/SQLEditor/variableCompletions.tsx index 653c7177e3..10df934e5b 100644 --- a/packages/app/src/components/SQLEditor/variableCompletions.tsx +++ b/packages/app/src/components/SQLEditor/variableCompletions.tsx @@ -6,6 +6,7 @@ import { } from '@hyperdx/common-utils/dist/macros'; import { ChartVariable } from '@hyperdx/common-utils/dist/types'; import { + isFilterSingleSelect, substituteVariables, TemplateLanguage, VariableFormat, @@ -30,8 +31,10 @@ const COMPLETION_FORMATS: Record< '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.', }, promql: { + promql: + '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.', regex: - 'The default format, written out. A regex alternation, escaped for the string literal it sits in. e.g. (a|b|c)', + 'A regex alternation, always regex escaped, and escaped for the double-quoted string literal it sits in. e.g. (a|b|c)', csv: 'Comma-separated and unquoted, with no escaping.', }, // Lucene inputs suggest only the bare `$name` reference. @@ -186,7 +189,9 @@ function getPromqlVariableCompletions( return [ reference( `$${name}`, - `The selected values of ${name} as a regex alternation, for use inside a matcher such as {label=~"$${name}"}. Matches everything when nothing is selected.`, + isFilterSingleSelect(variable) + ? `The selected value of ${name} as written, for use inside an exact matcher such as {label="$${name}"}. An empty string when nothing is selected.` + : `The selected values of ${name} as a regex alternation, for use inside a matcher such as {label=~"$${name}"}. Matches everything when nothing is selected.`, ), reference( `\${${name}}`, diff --git a/packages/app/tests/e2e/features/dashboard-filter-variables.spec.ts b/packages/app/tests/e2e/features/dashboard-filter-variables.spec.ts index 2e94e6e3f5..1dc8a2e734 100644 --- a/packages/app/tests/e2e/features/dashboard-filter-variables.spec.ts +++ b/packages/app/tests/e2e/features/dashboard-filter-variables.spec.ts @@ -375,6 +375,56 @@ test.describe( }); }); + test('matches a single-select variable exactly', async ({ page }) => { + test.setTimeout(120000); + + const dashboardPage = new DashboardPage(page); + const seriesAreas = page + .locator('.recharts-responsive-container') + .first() + .locator('.recharts-area'); + + await test.step('Create a dashboard with a single-select $svc variable', async () => { + await dashboardPage.goto(); + await dashboardPage.createNewDashboard(); + await dashboardPage.openEditFiltersModal(); + await dashboardPage.addStaticListFilterToDashboard( + 'Service', + SERVICES.slice(0, 2), + { variableName: 'svc', singleSelect: true }, + ); + await dashboardPage.closeFiltersModal(); + }); + + await test.step('Add a PromQL tile with an exact $svc matcher', async () => { + await openPromqlTileEditor(dashboardPage); + await dashboardPage.chartEditor.setChartName('PromQL tile'); + await dashboardPage.chartEditor.replacePromqlExpression( + `${E2E_PROMQL_METRIC_NAME}{service="$svc"}`, + ); + await dashboardPage.chartEditor.save(); + await expect(dashboardPage.getTiles()).toHaveCount(1, { + timeout: 10000, + }); + }); + + await test.step('With nothing selected, no series match', async () => { + // A zero series count also holds while the tile is still loading. + await expect( + dashboardPage + .getTiles() + .first() + .getByText('No data found within time range.'), + ).toBeVisible({ timeout: 30000 }); + await expect(seriesAreas).toHaveCount(0); + }); + + await test.step('Selecting a service matches its series', async () => { + await dashboardPage.toggleFilterValue('Service', SERVICES[0]); + await expect(seriesAreas).toHaveCount(1, { timeout: 30000 }); + }); + }); + /** * The expression above is only writable if the editor tells you the * variable exists. Three completion sources share the PromQL input — @@ -417,9 +467,10 @@ test.describe( const info = page.locator('.cm-completionInfo'); await info.waitFor({ state: 'visible', timeout: 10000 }); - // Nothing is selected on this dashboard, and regex is promql's default - // format — so the bare reference previews the match-everything state - // that makes the tile above valid before anything is picked. + // Nothing is selected on this dashboard, and a multi-select variable + // renders as a regex by default — so the bare reference previews the + // match-everything state that makes the tile above valid before + // anything is picked. await expect(info.locator('.cm-completionInfo-footnote')).toHaveText( 'Expands to: .*', ); diff --git a/packages/common-utils/src/__tests__/filters.test.ts b/packages/common-utils/src/__tests__/filters.test.ts index 4c79bedb7a..3a68bc1a97 100644 --- a/packages/common-utils/src/__tests__/filters.test.ts +++ b/packages/common-utils/src/__tests__/filters.test.ts @@ -14,7 +14,6 @@ import { isFilterBroadcastEnabled, isFilterGlobalRequirement, isFilterRequired, - isFilterSingleSelect, isFilterVariableEnabled, isQueryExpressionFilter, isRenderablePinnedFilter, @@ -38,6 +37,7 @@ import { DASHBOARD_VARIABLE_NAME_MAX_LENGTH, DASHBOARD_VARIABLE_NAME_PATTERN_ANCHORED, } from '@/types'; +import { isFilterSingleSelect } from '@/variables'; describe('filters', () => { describe('filtersToQuery', () => { @@ -1159,6 +1159,11 @@ describe('filters', () => { 'match(ServiceName, ${svc:regex})', 'sql', ], + [ + 'a promql-formatted reference', + "match(ServiceName, '${svc:promql}')", + 'sql', + ], ] as const)('reports nothing for %s', (_label, where, whereLanguage) => { expect( getPendingFilterValuesVariables({ where, whereLanguage }, [svc([])]), diff --git a/packages/common-utils/src/__tests__/variables.test.ts b/packages/common-utils/src/__tests__/variables.test.ts index dd7dc12366..d8701b5acc 100644 --- a/packages/common-utils/src/__tests__/variables.test.ts +++ b/packages/common-utils/src/__tests__/variables.test.ts @@ -56,78 +56,125 @@ const builderConfig = ( describe('formatVariableValues', () => { describe('sqlstring', () => { it('renders NULL when nothing is selected', () => { - expect(formatVariableValues([], 'sqlstring')).toBe('NULL'); + expect(formatVariableValues({ values: [] }, 'sqlstring')).toBe('NULL'); }); it('renders a single quoted value', () => { - expect(formatVariableValues(['api'], 'sqlstring')).toBe("'api'"); + expect(formatVariableValues({ values: ['api'] }, 'sqlstring')).toBe( + "'api'", + ); }); it('renders a comma-separated list', () => { - expect(formatVariableValues(['api', 'web'], 'sqlstring')).toBe( - "'api', 'web'", - ); + expect( + formatVariableValues({ values: ['api', 'web'] }, 'sqlstring'), + ).toBe("'api', 'web'"); }); it('escapes quotes and backslashes the same way the broadcast path does', () => { - expect(formatVariableValues(["o'brien", 'a\\b'], 'sqlstring')).toBe( - "'o''brien', 'a\\\\b'", - ); + expect( + formatVariableValues({ values: ["o'brien", 'a\\b'] }, 'sqlstring'), + ).toBe("'o''brien', 'a\\\\b'"); }); }); describe('regex', () => { it('matches anything when nothing is selected', () => { - expect(formatVariableValues([], 'regex')).toBe('.*'); + expect(formatVariableValues({ values: [] }, 'regex')).toBe('.*'); }); it('leaves a single value unwrapped', () => { - expect(formatVariableValues(['api'], 'regex')).toBe('api'); + expect(formatVariableValues({ values: ['api'] }, 'regex')).toBe('api'); }); it('wraps an alternation of multiple values', () => { - expect(formatVariableValues(['api', 'web'], 'regex')).toBe('(api|web)'); + expect(formatVariableValues({ values: ['api', 'web'] }, 'regex')).toBe( + '(api|web)', + ); }); it('escapes regex metacharacters', () => { - expect(formatVariableValues(['a.b+c', 'x(y)'], 'regex')).toBe( + expect(formatVariableValues({ values: ['a.b+c', 'x(y)'] }, 'regex')).toBe( '(a\\.b\\+c|x\\(y\\))', ); }); }); + describe('regex for a single-select variable', () => { + it('still escapes regex metacharacters', () => { + expect( + formatVariableValues({ values: ['a.b'], maxSelections: 1 }, 'regex'), + ).toBe('a\\.b'); + }); + }); + + describe('promql', () => { + const single = (values: string[]) => + formatVariableValues({ values, maxSelections: 1 }, 'promql'); + const multi = (values: string[]) => + formatVariableValues({ values }, 'promql'); + + it('renders a single-select value without regex escaping', () => { + expect(single(['a.b+c'])).toBe('a.b+c'); + }); + + it('renders an empty string for an empty single-select variable', () => { + expect(single([])).toBe(''); + }); + + it('renders only the first value of a single-select variable', () => { + expect(single(['api', 'web'])).toBe('api'); + }); + + it('renders a multi-select variable as an escaped alternation', () => { + expect(multi(['a.b', 'web'])).toBe('(a\\.b|web)'); + }); + + it('escapes a multi-select variable even with one value selected', () => { + expect(multi(['a.b'])).toBe('a\\.b'); + }); + + it('matches anything for an empty multi-select variable', () => { + expect(multi([])).toBe('.*'); + }); + }); + describe('csv', () => { it('renders empty when nothing is selected', () => { - expect(formatVariableValues([], 'csv')).toBe(''); + expect(formatVariableValues({ values: [] }, 'csv')).toBe(''); }); it('joins values with commas', () => { - expect(formatVariableValues(['api', 'web'], 'csv')).toBe('api,web'); + expect(formatVariableValues({ values: ['api', 'web'] }, 'csv')).toBe( + 'api,web', + ); }); }); describe('markdown', () => { it('renders empty when nothing is selected', () => { - expect(formatVariableValues([], 'markdown')).toBe(''); + expect(formatVariableValues({ values: [] }, 'markdown')).toBe(''); }); it('joins values with a comma and a space', () => { - expect(formatVariableValues(['api', 'web'], 'markdown')).toBe('api, web'); + expect(formatVariableValues({ values: ['api', 'web'] }, 'markdown')).toBe( + 'api, web', + ); }); it('escapes markdown syntax in values', () => { expect( formatVariableValues( - ['[x](https://e.com)', '*a_b* \\ `c`'], + { values: ['[x](https://e.com)', '*a_b* \\ `c`'] }, 'markdown', ), ).toBe('\\[x\\]\\(https\\:\\/\\/e\\.com\\), \\*a\\_b\\* \\\\ \\`c\\`'); }); it('replaces newlines with spaces', () => { - expect(formatVariableValues(['a\n# b\r\nc'], 'markdown')).toBe( - 'a \\# b c', - ); + expect( + formatVariableValues({ values: ['a\n# b\r\nc'] }, 'markdown'), + ).toBe('a \\# b c'); }); }); @@ -135,21 +182,23 @@ describe('formatVariableValues', () => { it('renders an empty term when nothing is selected', () => { // Parenthesized so it stays a no-op in a field-scoped position; see the // queryParser test that pins `ServiceName:("")` to `1=1`. - expect(formatVariableValues([], 'lucene')).toBe('("")'); + expect(formatVariableValues({ values: [] }, 'lucene')).toBe('("")'); }); it('renders a single quoted term', () => { - expect(formatVariableValues(['api'], 'lucene')).toBe('("api")'); + expect(formatVariableValues({ values: ['api'] }, 'lucene')).toBe( + '("api")', + ); }); it('ORs multiple terms', () => { - expect(formatVariableValues(['api', 'web'], 'lucene')).toBe( + expect(formatVariableValues({ values: ['api', 'web'] }, 'lucene')).toBe( '("api" OR "web")', ); }); it('escapes backslashes and double quotes', () => { - expect(formatVariableValues(['a"b', 'c\\d'], 'lucene')).toBe( + expect(formatVariableValues({ values: ['a"b', 'c\\d'] }, 'lucene')).toBe( '("a\\"b" OR "c\\\\d")', ); }); @@ -932,10 +981,42 @@ describe('substituteVariables for promql', () => { }); }); + describe('a single-select variable', () => { + const singleSelect = (values: string[]): ChartVariable => ({ + ...variable('service', values), + maxSelections: 1, + }); + + it('defaults to the unescaped value, for an exact matcher', () => { + expect(promql('up{service="$service"}', [singleSelect(['v1.2'])])).toBe( + 'up{service="v1.2"}', + ); + }); + + it('defaults to an empty string when nothing is selected', () => { + expect(promql('up{service="$service"}', [singleSelect([])])).toBe( + 'up{service=""}', + ); + }); + + it('still escapes the value for the string literal', () => { + expect(promql('up{service="$service"}', [singleSelect(['a"b\\c'])])).toBe( + 'up{service="a\\"b\\\\c"}', + ); + }); + + it('is regex escaped when the regex format is requested', () => { + expect( + promql('up{service=~"${service:regex}"}', [singleSelect(['v1.2'])]), + ).toBe('up{service=~"v1\\\\.2"}'); + }); + }); + describe('behaviour', () => { - it('uses the regex format for an unformatted reference', () => { + it('uses the promql format for an unformatted reference', () => { expect(promql('${service}', [SERVICE])).toBe('(api|web)'); expect(promql('$service', [SERVICE])).toBe('(api|web)'); + expect(promql('${service:promql}', [SERVICE])).toBe('(api|web)'); }); it('still honours an explicitly requested format', () => { @@ -999,6 +1080,15 @@ describe('substituteVariables regex escaping for sql', () => { it('renders the empty selection as an unconstrained pattern', () => { expect(sqlMatch([])).toBe("match(x, '.*')"); }); + + it('escapes a single-select promql value for the SQL literal only', () => { + expect( + substituteVariables("x = '${service:promql}'", { + variables: [{ ...variable('service', ["a.b'c"]), maxSelections: 1 }], + inputLanguage: 'sql', + }), + ).toBe("x = 'a.b''c'"); + }); }); describe('substituteVariables formats the language must not re-escape', () => { @@ -1955,6 +2045,38 @@ describe('validateVariableReferencesInTemplate', () => { ]); }); + it('suggests a regex matcher for an unquoted single-select regex reference', () => { + const { warnings } = promql('up{service=${service:regex}}', [ + { ...SERVICE, maxSelections: 1 }, + ]); + + expect(warnings).toEqual([ + '${service:regex} expands to a regular expression, which is only valid inside a quoted matcher value. Wrap it as {