Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/promql-variable-format.md
Original file line number Diff line number Diff line change
@@ -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
1 change: 1 addition & 0 deletions packages/api/src/mcp/prompts/dashboards/content.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 <empty> use INSIDE a string literal
markdown a, b <empty> the default in markdown tiles; markdown syntax in values is escaped

Expand Down
5 changes: 4 additions & 1 deletion packages/api/src/mcp/tools/dashboards/schemas.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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.',
),
};

Expand Down
2 changes: 1 addition & 1 deletion packages/api/src/mcp/tools/dashboards/variables.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
2 changes: 1 addition & 1 deletion packages/app/src/DashboardFilters.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,6 @@ import {
getPendingFilterValuesVariables,
isFilterGlobalRequirement,
isFilterRequired,
isFilterSingleSelect,
isFilterVariableEnabled,
isQueryExpressionFilter,
isStaticListFilter,
Expand All @@ -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';

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@ import {
isFilterBroadcastEnabled,
isFilterGlobalRequirement,
isFilterRequired,
isFilterSingleSelect,
isFilterVariableEnabled,
} from '@hyperdx/common-utils/dist/filters';
import {
Expand All @@ -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';

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ describe('buildPromqlVariableCompletions', () => {
expect(labels([SERVICE])).toEqual([
'$service',
'${service}',
'${service:promql}',
'${service:regex}',
'${service:csv}',
]);
Expand Down Expand Up @@ -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}',
]);
Expand All @@ -92,14 +95,15 @@ 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) => {
expect(footnoteOf([SERVICE], label)).toBe(expected);
});

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: .*');
Expand All @@ -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');
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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', () => {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ import {
} from '@hyperdx/common-utils/dist/macros';
import { ChartVariable } from '@hyperdx/common-utils/dist/types';
import {
isFilterSingleSelect,
substituteVariables,
TemplateLanguage,
VariableFormat,
Expand All @@ -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.
Expand Down Expand Up @@ -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}}`,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 —
Expand Down Expand Up @@ -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: .*',
);
Expand Down
7 changes: 6 additions & 1 deletion packages/common-utils/src/__tests__/filters.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@ import {
isFilterBroadcastEnabled,
isFilterGlobalRequirement,
isFilterRequired,
isFilterSingleSelect,
isFilterVariableEnabled,
isQueryExpressionFilter,
isRenderablePinnedFilter,
Expand All @@ -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', () => {
Expand Down Expand Up @@ -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([])]),
Expand Down
Loading
Loading