From 1ecb71d65804085a05dfbc94b03f668961307cac Mon Sep 17 00:00:00 2001 From: Aaron Knudtson <87577305+knudtty@users.noreply.github.com> Date: Mon, 16 Nov 2026 13:58:13 -0500 Subject: [PATCH] feat: Grafana global variables in raw SQL and link templates Raw SQL charts and row-click link templates now expand ${__from}/${__to} (with :date, :date:iso, :date:seconds), $__range/_s/_ms, ${__timezone}, ${__url_time_range} and ${__all_variables}, so SQL and links migrated from Grafana work unchanged. --- .changeset/grafana-global-variables.md | 13 ++ .../api/src/mcp/prompts/dashboards/content.ts | 10 +- packages/api/src/mcp/tools/query/sql.ts | 3 + packages/app/src/components/DBTableChart.tsx | 1 + packages/app/src/hooks/useChartConfig.tsx | 7 +- .../app/src/hooks/useOffsetPaginatedQuery.tsx | 4 +- .../app/src/hooks/useOnClickLinkBuilder.ts | 26 ++- packages/app/src/useDisplayTimeZone.ts | 26 ++- .../common-utils/src/__tests__/macros.test.ts | 69 ++++++ .../src/__tests__/variables.test.ts | 18 ++ .../src/core/__tests__/linkUrlBuilder.test.ts | 40 ++++ .../common-utils/src/core/linkUrlBuilder.ts | 64 ++++-- packages/common-utils/src/globalVariables.ts | 202 ++++++++++++++++++ packages/common-utils/src/macros.ts | 30 ++- packages/common-utils/src/types.ts | 3 + packages/common-utils/src/variables.ts | 25 ++- 16 files changed, 517 insertions(+), 24 deletions(-) create mode 100644 .changeset/grafana-global-variables.md create mode 100644 packages/common-utils/src/globalVariables.ts diff --git a/.changeset/grafana-global-variables.md b/.changeset/grafana-global-variables.md new file mode 100644 index 0000000000..32f68ca667 --- /dev/null +++ b/.changeset/grafana-global-variables.md @@ -0,0 +1,13 @@ +--- +'@hyperdx/common-utils': minor +'@hyperdx/app': minor +'@hyperdx/api': patch +--- + +feat: Grafana global variables in raw SQL and link templates + +Raw SQL charts and row-click link templates now expand `${__from}` / `${__to}` +(epoch ms, or `:date`, `:date:iso`, `:date:seconds`), `$__range`, `$__range_s`, +`$__range_ms`, `${__timezone}`, `${__url_time_range}` and `${__all_variables}`. +Each also works in the bare `$__name` form, and any macro can now be written in +braces, e.g. `${__fromTime}`. diff --git a/packages/api/src/mcp/prompts/dashboards/content.ts b/packages/api/src/mcp/prompts/dashboards/content.ts index 84c8199bb3..953184bcd1 100644 --- a/packages/api/src/mcp/prompts/dashboards/content.ts +++ b/packages/api/src/mcp/prompts/dashboards/content.ts @@ -775,6 +775,10 @@ SQL TEMPLATE REFERENCE: $__fromTime / $__toTime start/end as DateTime values $__fromTime_ms / $__toTime_ms start/end as DateTime64 values $__interval_s raw interval in seconds + \${__from} / \${__to} Grafana globals: start/end epoch ms; :date:iso or :date:seconds formats + $__range / $__range_s / $__range_ms range length as "3600s" / seconds / ms + \${__timezone} viewer's IANA time zone (UTC for alerts); quote it + \${__url_time_range} from=&to=; \${__all_variables} filters= $__filters dashboard filter conditions (resolves to 1=1 when none). REQUIRES sourceId on the tile. Without it, filters never apply. $__sourceTable the source's \`database\`.\`table\`. @@ -967,6 +971,10 @@ For configType: "sql" tiles, write ClickHouse SQL with template macros: $__fromTime / $__toTime start/end as DateTime values $__fromTime_ms / $__toTime_ms start/end as DateTime64 values $__interval_s raw interval in seconds (for arithmetic) + \${__from} / \${__to} Grafana globals: start/end epoch ms; :date:iso or :date:seconds formats + $__range / $__range_s / $__range_ms range length as "3600s" / seconds / ms + \${__timezone} viewer's IANA time zone (UTC for alerts); quote it + \${__url_time_range} from=&to=; \${__all_variables} filters= $__filters dashboard filter conditions (1=1 when none). REQUIRES sourceId on the tile. Set sourceId (unless the query reads multiple tables) so dashboard filters apply. @@ -1325,7 +1333,7 @@ Destination types: { type: "dashboard", target, whereLanguage, whereTemplate?, filters? } Opens another ClickStack dashboard owned by the same team. { type: "external", urlTemplate } - Opens an arbitrary external URL in a new tab (e.g. a Grafana or Langfuse dashboard, a runbook). The urlTemplate is rendered against the clicked row and the rendered value must be an absolute http(s) URL. It takes no target, whereLanguage, whereTemplate, or filters, and references no ClickStack source or dashboard. + Opens an arbitrary external URL in a new tab (e.g. a Grafana or Langfuse dashboard, a runbook). The urlTemplate is rendered against the clicked row and the rendered value must be an absolute http(s) URL. Every link template also expands the Grafana globals \${__from}, \${__to}, \${__from:date:iso}, $__range, \${__timezone}, \${__url_time_range} (from=&to=) and \${__all_variables} (filters=). It takes no target, whereLanguage, whereTemplate, or filters, and references no ClickStack source or dashboard. Target shape, how the destination is identified: target: { mode: "id", id: "" } diff --git a/packages/api/src/mcp/tools/query/sql.ts b/packages/api/src/mcp/tools/query/sql.ts index 82a33f7a8a..c7d3776b04 100644 --- a/packages/api/src/mcp/tools/query/sql.ts +++ b/packages/api/src/mcp/tools/query/sql.ts @@ -54,6 +54,9 @@ const sqlSchema = z.object({ ' $__timeInterval(column) — time bucket expression: toStartOfInterval(toDateTime(column), INTERVAL ...)\n' + ' $__timeInterval_ms(column) — same with millisecond precision\n' + ' $__interval_s — raw interval in seconds\n' + + ' ${__from} / ${__to} — start/end epoch ms; ${__from:date:iso} / ${__from:date:seconds} for other formats\n' + + ' $__range / $__range_s / $__range_ms — range length as 3600s / seconds / milliseconds\n' + + " ${__timezone} — the viewer's IANA time zone (UTC here); quote it\n" + ' $__filters — dashboard filter conditions (resolves to 1=1 when no filters)\n' + " $__sourceTable — the source's database.table. Requires sourceId.\n" + ' {intervalSeconds:Int64} / {intervalMilliseconds:Int64} — bucket size parameters\n\n' + diff --git a/packages/app/src/components/DBTableChart.tsx b/packages/app/src/components/DBTableChart.tsx index 028a6cae13..d1bf45b7bd 100644 --- a/packages/app/src/components/DBTableChart.tsx +++ b/packages/app/src/components/DBTableChart.tsx @@ -330,6 +330,7 @@ export default function DBTableChart({ const getRowAction = useOnClickLinkBuilder({ onClick: config.onClick, dateRange: queriedConfig.dateRange, + variables: config.variables, }); return ( diff --git a/packages/app/src/hooks/useChartConfig.tsx b/packages/app/src/hooks/useChartConfig.tsx index ed367f0c27..f9c6e0d7b5 100644 --- a/packages/app/src/hooks/useChartConfig.tsx +++ b/packages/app/src/hooks/useChartConfig.tsx @@ -50,6 +50,7 @@ import { useMetadataWithSettings } from '@/hooks/useMetadata'; import { useQueryAttribution } from '@/queryAttribution'; import { useSource } from '@/source'; import { ChartQueryResult } from '@/types'; +import { useWithDisplayTimeZone } from '@/useDisplayTimeZone'; import { stripClientSideConfigFields } from '@/utils/chartConfig'; import { queryPromqlChartConfig, @@ -358,10 +359,11 @@ export function appendChunk( * - `data.isComplete` indicates whether all chunks have been fetched. */ export function useQueriedChartConfig( - config: ChartConfigWithOptDateRange, + configProp: ChartConfigWithOptDateRange, options?: Partial> & AdditionalUseQueriedChartConfigOptions, ) { + const config = useWithDisplayTimeZone(configProp); const { enabled = true } = options ?? {}; const clickhouseClient = useClickhouseClient(); const attribution = useQueryAttribution(); @@ -501,9 +503,10 @@ export function useQueriedChartConfig( } export function useRenderedSqlChartConfig( - config: ChartConfigWithOptDateRange, + configProp: ChartConfigWithOptDateRange, options?: Partial>, ) { + const config = useWithDisplayTimeZone(configProp); const { enabled = true } = options ?? {}; const metadata = useMetadataWithSettings(); diff --git a/packages/app/src/hooks/useOffsetPaginatedQuery.tsx b/packages/app/src/hooks/useOffsetPaginatedQuery.tsx index 9492d435d0..e21fd1a4e6 100644 --- a/packages/app/src/hooks/useOffsetPaginatedQuery.tsx +++ b/packages/app/src/hooks/useOffsetPaginatedQuery.tsx @@ -41,6 +41,7 @@ import { useMetadataWithSettings } from '@/hooks/useMetadata'; import { useMVOptimizationExplanation } from '@/hooks/useMVOptimizationExplanation'; import { useQueryAttribution } from '@/queryAttribution'; import { useSource } from '@/source'; +import { useWithDisplayTimeZone } from '@/useDisplayTimeZone'; import { queryPromqlChartConfig } from '@/utils/promqlChartQuery'; import { DEFAULT_TIME_WINDOWS_SECONDS, @@ -478,7 +479,7 @@ function flattenData(data: TData | undefined): TQueryFnData | null { } export default function useOffsetPaginatedQuery( - config: ChartConfigWithOptTimestamp, + configProp: ChartConfigWithOptTimestamp, { isLive, keepPreviousData, @@ -494,6 +495,7 @@ export default function useOffsetPaginatedQuery( enableSmallFirstWindow?: boolean; } = {}, ) { + const config = useWithDisplayTimeZone(configProp); const { data: meData, isLoading: isLoadingMe } = api.useMe(); const key = queryKeyFn(queryKeyPrefix, config, meData?.team?.queryTimeout); const queryClient = useQueryClient(); diff --git a/packages/app/src/hooks/useOnClickLinkBuilder.ts b/packages/app/src/hooks/useOnClickLinkBuilder.ts index 5b58d8a5bd..25a2eee87d 100644 --- a/packages/app/src/hooks/useOnClickLinkBuilder.ts +++ b/packages/app/src/hooks/useOnClickLinkBuilder.ts @@ -5,12 +5,18 @@ import { renderOnClickExternal, renderOnClickSearch, } from '@hyperdx/common-utils/dist/core/linkUrlBuilder'; -import { isSearchableSource, OnClick } from '@hyperdx/common-utils/dist/types'; +import { + ChartVariable, + isSearchableSource, + OnClick, +} from '@hyperdx/common-utils/dist/types'; import { notifications } from '@mantine/notifications'; import { useDashboards } from '@/dashboard'; import { useSources } from '@/source'; +import { getLocalTimeZone } from '@/timeZone'; import { useTimeZoneLinkParam } from '@/timeZoneOverride'; +import { useDisplayTimeZone } from '@/useDisplayTimeZone'; /** * The action a row click should take. `url` is set when the row's @@ -49,13 +55,17 @@ export type RowAction = { export function useOnClickLinkBuilder({ onClick, dateRange, + variables, }: { onClick: OnClick | undefined; dateRange: [Date, Date]; + /** The dashboard's variables, read by `${__all_variables}`. */ + variables?: ChartVariable[]; }): ((row: Record) => RowAction) | null { const { data: sources } = useSources(); const { data: dashboards } = useDashboards(); const addTimeZone = useTimeZoneLinkParam(); + const timeZone = useDisplayTimeZone() ?? getLocalTimeZone(); const [sourceIdsByName, sourceIds, sourceNamesById] = useMemo(() => { const idsByName = new Map(); @@ -113,6 +123,8 @@ export function useOnClickLinkBuilder({ sourceIds, sourceIdsByName, dateRange, + timeZone, + variables, }) : onClick.type === 'dashboard' ? renderOnClickDashboard({ @@ -121,8 +133,16 @@ export function useOnClickLinkBuilder({ dashboardIds, dashboardIdsByName, dateRange, + timeZone, + variables, }) - : renderOnClickExternal({ onClick, row }); + : renderOnClickExternal({ + onClick, + row, + dateRange, + timeZone, + variables, + }); if (renderResult.ok) { return { @@ -163,6 +183,8 @@ export function useOnClickLinkBuilder({ sourceIdsByName, sourceNamesById, dateRange, + timeZone, + variables, dashboardIds, dashboardIdsByName, dashboardNamesById, diff --git a/packages/app/src/useDisplayTimeZone.ts b/packages/app/src/useDisplayTimeZone.ts index 162552db1d..bf43dd48c9 100644 --- a/packages/app/src/useDisplayTimeZone.ts +++ b/packages/app/src/useDisplayTimeZone.ts @@ -1,6 +1,9 @@ import { useMemo } from 'react'; +import { isRawSqlChartConfig } from '@hyperdx/common-utils/dist/guards'; +import { hasMacro } from '@hyperdx/common-utils/dist/macros'; +import { ChartConfigWithOptDateRange } from '@hyperdx/common-utils/dist/types'; -import { resolveTimeZonePreference } from './timeZone'; +import { getLocalTimeZone, resolveTimeZonePreference } from './timeZone'; import { useTimeZoneOverride } from './timeZoneOverride'; import { useUserPreferences } from './useUserPreferences'; @@ -20,3 +23,24 @@ export function useDisplayTimeZone(): string | undefined { [override, timeZone], ); } + +/** + * Adds the display time zone to a raw SQL config that reads `${__timezone}`. + * Other configs are returned as is, so a zone change doesn't refetch them. + */ +export function useWithDisplayTimeZone( + config: T, +): T { + const timeZone = useDisplayTimeZone() ?? getLocalTimeZone(); + return useMemo(() => { + try { + return isRawSqlChartConfig(config) && + hasMacro(config.sqlTemplate, 'timezone') + ? { ...config, timeZone } + : config; + } catch { + // A half-typed macro; rendering reports it. + return config; + } + }, [config, timeZone]); +} diff --git a/packages/common-utils/src/__tests__/macros.test.ts b/packages/common-utils/src/__tests__/macros.test.ts index d239e68c60..301658d779 100644 --- a/packages/common-utils/src/__tests__/macros.test.ts +++ b/packages/common-utils/src/__tests__/macros.test.ts @@ -361,6 +361,75 @@ describe('replaceMacros', () => { }); }); +describe('replaceMacros global variables', () => { + const dateRange: [Date, Date] = [new Date(1500), new Date(3601500)]; + + it.each([ + ['$__from', '1500'], + ['${__from}', '1500'], + ['${__to}', '3601500'], + ["'${__from:date}'", "'1970-01-01T00:00:01.500Z'"], + ["'${__to:date:iso}'", "'1970-01-01T01:00:01.500Z'"], + ['${__from:date:seconds}', '1'], + ['$__range', '3600s'], + ['${__range_s}', '3600'], + ['$__range_ms', '3600000'], + ["'${__timezone}'", "'UTC'"], + ["'${__url_time_range}'", "'from=1500&to=3601500'"], + ])('expands %s', (sqlTemplate, expected) => { + expect(replaceMacros({ sqlTemplate, dateRange })).toBe(expected); + }); + + it('leaves the longer macros sharing a prefix alone', () => { + expect(replaceMacros({ sqlTemplate: '$__fromTime_ms', dateRange })).toBe( + 'fromUnixTimestamp64Milli({startDateMilliseconds:Int64})', + ); + }); + + it('uses the query params without a date range, so validation sees a time filter', () => { + expect(replaceMacros({ sqlTemplate: '${__from:date:iso} ${__to}' })).toBe( + '{startDateMilliseconds:Int64} {endDateMilliseconds:Int64}', + ); + }); + + it('expands the configured time zone and rejects one that is not a zone name', () => { + expect( + replaceMacros({ + sqlTemplate: "'${__timezone}'", + timeZone: 'America/New_York', + }), + ).toBe("'America/New_York'"); + expect(() => + replaceMacros({ sqlTemplate: '$__timezone', timeZone: "x' OR 1=1" }), + ).toThrow("Invalid time zone 'x' OR 1=1'"); + }); + + it('encodes selected variables as a URL param that cannot end the SQL string', () => { + expect( + replaceMacros({ + sqlTemplate: "'${__all_variables}'", + variables: [variable('svc', ["a'b"]), EMPTY_SERVICE], + }), + ).toBe( + "'filters=%5B%7B%22type%22%3A%22variable%22%2C%22name%22%3A%22svc%22%2C%22values%22%3A%5B%22a%27b%22%5D%7D%5D'", + ); + }); + + it('rejects unsupported formats', () => { + expect(() => + replaceMacros({ sqlTemplate: '${__from:date:YYYY}', dateRange }), + ).toThrow("Unsupported format 'date:YYYY'"); + expect(() => + replaceMacros({ sqlTemplate: '${__range:raw}', dateRange }), + ).toThrow('takes no format'); + }); + + it('is detected by hasMacro in either form', () => { + expect(hasMacro('WHERE ts >= ${__from:date:seconds}', 'from')).toBe(true); + expect(hasMacro('WHERE ts >= $__fromTime', 'from')).toBe(false); + }); +}); + describe('replaceMacros with variables', () => { const variables = [ { name: 'service', expression: 'ServiceName', values: ['api', 'web'] }, diff --git a/packages/common-utils/src/__tests__/variables.test.ts b/packages/common-utils/src/__tests__/variables.test.ts index 9614f0310d..ec38d6f978 100644 --- a/packages/common-utils/src/__tests__/variables.test.ts +++ b/packages/common-utils/src/__tests__/variables.test.ts @@ -1470,6 +1470,24 @@ describe('filterReferencedVariables', () => { ); }); + it('keeps every variable when the SQL or a link reads ${__all_variables}', () => { + expect( + filterReferencedVariables(rawSqlConfig("'$__all_variables'"), variables), + ).toEqual(variables); + expect( + filterReferencedVariables( + { + ...rawSqlConfig('SELECT 1'), + onClick: { + type: 'external', + urlTemplate: 'https://example.com/?${__all_variables}', + }, + }, + variables, + ), + ).toEqual(variables); + }); + it('keeps the variables a PromQL expression references', () => { expect( filterReferencedVariables( diff --git a/packages/common-utils/src/core/__tests__/linkUrlBuilder.test.ts b/packages/common-utils/src/core/__tests__/linkUrlBuilder.test.ts index 367b17c241..c44317465c 100644 --- a/packages/common-utils/src/core/__tests__/linkUrlBuilder.test.ts +++ b/packages/common-utils/src/core/__tests__/linkUrlBuilder.test.ts @@ -903,6 +903,46 @@ describe('renderOnClickExternal', () => { } }); + it('expands Grafana global variables alongside row columns', () => { + const onClick: OnClickExternal = { + type: 'external', + urlTemplate: + 'https://grafana.example.com/d/abc?svc={{ServiceName}}&${__url_time_range}&tz=${__timezone}&start=${__from:date:iso}&${__all_variables}#$__to', + }; + const result = renderOnClickExternal({ + onClick, + row: { ServiceName: 'checkout' }, + dateRange: [new Date(1000), new Date(61000)], + timeZone: 'Etc/GMT+5', + variables: [ + { name: 'env', values: ["it's"] }, + { name: 'empty', values: [] }, + ], + }); + expect(result).toEqual({ + ok: true, + url: + 'https://grafana.example.com/d/abc?svc=checkout&from=1000&to=61000&tz=Etc%2FGMT%2B5' + + '&start=1970-01-01T00:00:01.000Z' + + '&filters=%5B%7B%22type%22%3A%22variable%22%2C%22name%22%3A%22env%22%2C%22values%22%3A%5B%22it%27s%22%5D%7D%5D' + + '#61000', + }); + }); + + it('reports an unsupported global variable format', () => { + const result = renderOnClickExternal({ + onClick: { + type: 'external', + urlTemplate: 'https://example.com/?t=${__from:date:YYYY}', + }, + row: {}, + dateRange: [new Date(0), new Date(1)], + }); + expect(result.ok).toBe(false); + if (!result.ok) + expect(result.error).toContain("Unsupported format 'date:YYYY'"); + }); + it('allows http URLs', () => { const onClick: OnClickExternal = { type: 'external', diff --git a/packages/common-utils/src/core/linkUrlBuilder.ts b/packages/common-utils/src/core/linkUrlBuilder.ts index 9ebbda7c33..f072990f20 100644 --- a/packages/common-utils/src/core/linkUrlBuilder.ts +++ b/packages/common-utils/src/core/linkUrlBuilder.ts @@ -1,5 +1,11 @@ import { FilterState, filtersToQuery } from '@/filters'; +import { + expandLinkGlobalVariables, + GlobalVariableContext, +} from '@/globalVariables'; +import { MacroExpansionError } from '@/macroErrors'; import type { + ChartVariable, Filter, OnClick, OnClickDashboard, @@ -23,18 +29,20 @@ export type LinkBuildResult = function renderOrError( template: string, rowData: Record, + globals: GlobalVariableContext, options?: { encodeValues?: boolean }, ): { ok: true; value: string } | { ok: false; error: string } { try { + const expanded = expandLinkGlobalVariables(template, globals, options); const value = options?.encodeValues - ? renderUrlTemplate(template, rowData) - : renderLinkTemplate(template, rowData); + ? renderUrlTemplate(expanded, rowData) + : renderLinkTemplate(expanded, rowData); return { ok: true, value }; } catch (err) { const message = err instanceof MissingTemplateVariableError ? `Row has no column '${err.variable}'` - : err instanceof LinkTemplateError + : err instanceof LinkTemplateError || err instanceof MacroExpansionError ? err.message : String(err); return { @@ -54,12 +62,13 @@ function renderOrError( function renderFilterTemplates( templates: OnClickFilterTemplate[] | undefined, row: Record, + globals: GlobalVariableContext, ): { ok: true; filters: Filter[] } | { ok: false; error: string } { if (!templates || templates.length === 0) return { ok: true, filters: [] }; const state: FilterState = {}; for (const template of templates) { - const rendered = renderOrError(template.template, row); + const rendered = renderOrError(template.template, row, globals); if (!rendered.ok) return rendered; if (state[template.expression]) { @@ -84,13 +93,18 @@ export function renderOnClickSearch({ sourceIds, sourceIdsByName, dateRange, + timeZone, + variables, }: { onClick: OnClickSearch; row: Record; sourceIds: Set; sourceIdsByName: Map; dateRange: [Date, Date]; + timeZone?: string; + variables?: ChartVariable[]; }): LinkBuildResult { + const globals = { dateRange, timeZone, variables }; let sourceId; if (onClick.target.mode === 'id') { if (!sourceIds.has(onClick.target.id)) { @@ -102,7 +116,11 @@ export function renderOnClickSearch({ sourceId = onClick.target.id; } else { // Render the source name template - const sourceNameRenderResult = renderOrError(onClick.target.template, row); + const sourceNameRenderResult = renderOrError( + onClick.target.template, + row, + globals, + ); if (!sourceNameRenderResult.ok) return sourceNameRenderResult; // Find the matching source's ID @@ -132,7 +150,7 @@ export function renderOnClickSearch({ let where = ''; if (onClick.whereTemplate) { - const whereResult = renderOrError(onClick.whereTemplate, row); + const whereResult = renderOrError(onClick.whereTemplate, row, globals); if (!whereResult.ok) return whereResult; where = whereResult.value; } @@ -146,7 +164,11 @@ export function renderOnClickSearch({ to: String(dateRange[1].getTime()), }); - const filterRenderResult = renderFilterTemplates(onClick.filters, row); + const filterRenderResult = renderFilterTemplates( + onClick.filters, + row, + globals, + ); if (!filterRenderResult.ok) return filterRenderResult; if (filterRenderResult.filters.length > 0) { @@ -168,13 +190,18 @@ export function renderOnClickDashboard({ dashboardIds, dashboardIdsByName, dateRange, + timeZone, + variables, }: { onClick: OnClickDashboard; row: Record; dashboardIds: Set; dashboardIdsByName: Map; dateRange: [Date, Date]; + timeZone?: string; + variables?: ChartVariable[]; }): LinkBuildResult { + const globals = { dateRange, timeZone, variables }; let dashboardId; if (onClick.target.mode === 'id') { if (!dashboardIds.has(onClick.target.id)) { @@ -189,6 +216,7 @@ export function renderOnClickDashboard({ const dashboardNameRenderResult = renderOrError( onClick.target.template, row, + globals, ); if (!dashboardNameRenderResult.ok) return dashboardNameRenderResult; @@ -220,7 +248,7 @@ export function renderOnClickDashboard({ // Render the dashboard's global WHERE condition, if any let where = ''; if (onClick.whereTemplate) { - const whereResult = renderOrError(onClick.whereTemplate, row); + const whereResult = renderOrError(onClick.whereTemplate, row, globals); if (!whereResult.ok) return whereResult; where = whereResult.value; } @@ -232,7 +260,11 @@ export function renderOnClickDashboard({ to: String(dateRange[1].getTime()), }); - const filterRenderResult = renderFilterTemplates(onClick.filters, row); + const filterRenderResult = renderFilterTemplates( + onClick.filters, + row, + globals, + ); if (!filterRenderResult.ok) return filterRenderResult; if (filterRenderResult.filters.length > 0) { @@ -269,13 +301,19 @@ function isAllowedExternalUrl(url: string): boolean { export function renderOnClickExternal({ onClick, row, + dateRange, + timeZone, + variables, }: { onClick: OnClickExternal; row: Record; -}): LinkBuildResult { - const rendered = renderOrError(onClick.urlTemplate, row, { - encodeValues: true, - }); +} & GlobalVariableContext): LinkBuildResult { + const rendered = renderOrError( + onClick.urlTemplate, + row, + { dateRange, timeZone, variables }, + { encodeValues: true }, + ); if (!rendered.ok) return rendered; const url = rendered.value.trim(); diff --git a/packages/common-utils/src/globalVariables.ts b/packages/common-utils/src/globalVariables.ts new file mode 100644 index 0000000000..275e1629d7 --- /dev/null +++ b/packages/common-utils/src/globalVariables.ts @@ -0,0 +1,202 @@ +import { MacroExpansionError } from './macroErrors'; +import { RawSqlQueryParam, renderQueryParam } from './rawSqlParams'; +import { ChartVariable, VariableFilterValue } from './types'; +import { scanTemplateTokens } from './variables'; + +/** + * Grafana-compatible global variables (`$__from`, `${__from:date:iso}`, + * `$__range`, `${__timezone}`, `${__url_time_range}`, `${__all_variables}`), + * shared by raw SQL templates and link templates. + */ +export type GlobalVariableContext = { + dateRange?: [Date, Date]; + /** IANA zone the user views times in. Defaults to UTC, e.g. for alerts. */ + timeZone?: string; + variables?: ChartVariable[]; +}; + +type GlobalVariable = { + name: string; + minArgs: number; + maxArgs: number; + description: string; + expand: (ctx: GlobalVariableContext, args: string[]) => string; +}; + +const TIME_FORMATS = ['date', 'date:iso', 'date:seconds']; + +// shortcut: no custom moment.js formats (${__from:date:YYYY-MM}), add a token translation if users need them. +function formatTime( + name: 'from' | 'to', + ms: number | undefined, + format: string | undefined, +): string { + if (format != null && !TIME_FORMATS.includes(format)) { + throw new MacroExpansionError( + name, + `Unsupported format '${format}' in '\${__${name}:${format}}'. Expected one of: ${TIME_FORMATS.join(', ')}.`, + ); + } + // Without a date range (saved-config validation) the query param stands in, + // so the time-range checks still see the template uses the range. + if (ms == null) { + return renderQueryParam( + name === 'from' + ? RawSqlQueryParam.startDateMilliseconds + : RawSqlQueryParam.endDateMilliseconds, + ); + } + if (format === 'date:seconds') return String(Math.floor(ms / 1000)); + if (format != null) return new Date(ms).toISOString(); + return String(ms); +} + +const rangeMs = ({ dateRange }: GlobalVariableContext) => + dateRange ? dateRange[1].getTime() - dateRange[0].getTime() : 0; + +// IANA names only, since the value is interpolated into SQL and URLs as written. +const TIME_ZONE_PATTERN = /^[A-Za-z][A-Za-z0-9_+\-/]*$/; + +// encodeURIComponent leaves `'` alone, which would end a SQL string literal. +const encodeUrlValue = (value: string) => + encodeURIComponent(value).replace(/'/g, '%27'); + +export const GLOBAL_VARIABLES = [ + { + name: 'from', + minArgs: 0, + maxArgs: 1, + description: + 'Start of the selected time range in epoch milliseconds. ${__from:date} or ${__from:date:iso} gives ISO 8601, ${__from:date:seconds} gives epoch seconds.', + expand: (ctx, args) => + formatTime('from', ctx.dateRange?.[0].getTime(), args[0]), + }, + { + name: 'to', + minArgs: 0, + maxArgs: 1, + description: + 'End of the selected time range in epoch milliseconds. ${__to:date} or ${__to:date:iso} gives ISO 8601, ${__to:date:seconds} gives epoch seconds.', + expand: (ctx, args) => + formatTime('to', ctx.dateRange?.[1].getTime(), args[0]), + }, + { + name: 'range', + minArgs: 0, + maxArgs: 0, + description: + 'Length of the selected time range as a duration in seconds, such as 3600s.', + expand: ctx => `${Math.round(rangeMs(ctx) / 1000)}s`, + }, + { + name: 'range_s', + minArgs: 0, + maxArgs: 0, + description: 'Length of the selected time range, in seconds.', + expand: ctx => String(Math.round(rangeMs(ctx) / 1000)), + }, + { + name: 'range_ms', + minArgs: 0, + maxArgs: 0, + description: 'Length of the selected time range, in milliseconds.', + expand: ctx => String(rangeMs(ctx)), + }, + { + name: 'timezone', + minArgs: 0, + maxArgs: 0, + description: + "The time zone times are shown in, such as America/New_York. Use it quoted, e.g. toTimeZone(ts, '${__timezone}').", + expand: ({ timeZone = 'UTC' }) => { + if (!TIME_ZONE_PATTERN.test(timeZone)) { + throw new MacroExpansionError( + 'timezone', + `Invalid time zone '${timeZone}'.`, + ); + } + return timeZone; + }, + }, + { + name: 'url_time_range', + minArgs: 0, + maxArgs: 0, + description: + 'The selected time range as URL query params: from=&to=.', + expand: ({ dateRange }) => + dateRange + ? `from=${dateRange[0].getTime()}&to=${dateRange[1].getTime()}` + : '', + }, + { + name: 'all_variables', + minArgs: 0, + maxArgs: 0, + description: + "Every dashboard variable's selection as a filters=<...> URL query param, so a link to another dashboard carries them.", + expand: ({ variables = [] }) => { + const entries: VariableFilterValue[] = variables + .filter(({ values }) => values.length > 0) + .map(({ name, values }) => ({ type: 'variable', name, values })); + return `filters=${encodeUrlValue(JSON.stringify(entries))}`; + }, + }, +] as const satisfies readonly GlobalVariable[]; + +export type GlobalVariableName = (typeof GLOBAL_VARIABLES)[number]['name']; + +export const GLOBAL_VARIABLE_NAMES: readonly GlobalVariableName[] = + GLOBAL_VARIABLES.map(({ name }) => name); + +const GLOBAL_VARIABLES_BY_NAME = new Map( + GLOBAL_VARIABLES.map(variable => [variable.name, variable]), +); + +/** Expand one global variable. `args` holds the format, as in `${__from:date:iso}`. */ +export function expandGlobalVariable( + name: GlobalVariableName, + ctx: GlobalVariableContext, + args: string[], +): string { + const variable = GLOBAL_VARIABLES_BY_NAME.get(name)!; + if (args.length > variable.maxArgs) { + throw new MacroExpansionError( + name, + `'$__${name}' takes ${variable.maxArgs === 0 ? 'no format' : 'at most one format'}, but got '${args.join(', ')}'.`, + ); + } + return variable.expand(ctx, args); +} + +const isGlobalVariableName = (name: string): name is GlobalVariableName => + GLOBAL_VARIABLES_BY_NAME.has(name); + +/** + * Expand the global variables in a link template, leaving everything else + * (Handlebars, `$name` references) as written. Values are URL-safe, so they + * can't introduce Handlebars syntax. + */ +export function expandLinkGlobalVariables( + template: string, + ctx: GlobalVariableContext, + { encodeValues = false }: { encodeValues?: boolean } = {}, +): string { + return scanTemplateTokens(template, GLOBAL_VARIABLE_NAMES, { + onMalformed: 'skip', + // A URL's `#fragment` isn't a SQL comment. + skipSqlComments: false, + }) + .map(token => { + if (token.kind === 'text') return token.text; + if (token.kind !== 'macro' || !isGlobalVariableName(token.name)) { + return token.raw; + } + const value = expandGlobalVariable(token.name, ctx, token.args); + // `Etc/GMT+5` would read back as a space in a query string. + return encodeValues && token.name === 'timezone' + ? encodeUrlValue(value) + : value; + }) + .join(''); +} diff --git a/packages/common-utils/src/macros.ts b/packages/common-utils/src/macros.ts index 5c98c342e1..9de1643796 100644 --- a/packages/common-utils/src/macros.ts +++ b/packages/common-utils/src/macros.ts @@ -8,10 +8,16 @@ import { } from './core/promql'; import { injectPromqlLabelMatchers } from './core/promqlLabelInjection'; import { splitAndTrimWithBracket } from './core/utils'; +import { + expandGlobalVariable, + GLOBAL_VARIABLES, + GlobalVariableName, +} from './globalVariables'; import { MacroExpansionError, MalformedMacroArgsError } from './macroErrors'; import { RawSqlQueryParam, renderQueryParam } from './rawSqlParams'; import { ChartVariable, + DateRange, DisplayType, MetricsDataType, MetricsDataTypeSchema, @@ -204,6 +210,7 @@ export type MacroName = | (typeof MACROS)[number]['name'] | 'filters' | 'sourceTable' + | GlobalVariableName | VariableMacroName; const FILTERS_MACRO_DESCRIPTION = @@ -244,6 +251,12 @@ export const MACRO_SUGGESTIONS: MacroSuggestion[] = [ maxArgs: 0, description: `The selected metrics source's ${type} table, fully qualified.`, })), + ...GLOBAL_VARIABLES.map(({ name, minArgs, maxArgs, description }) => ({ + name, + minArgs, + maxArgs, + description, + })), ]; /** Macros that only resolve when the chart is rendered with a variable context */ @@ -293,6 +306,8 @@ export const TIME_RANGE_MACROS = [ 'toTime', 'fromTime_ms', 'toTime_ms', + 'from', + 'to', ] as const; /** @@ -372,7 +387,7 @@ export function getSourceTableMacroArgCounts(sqlTemplate: string): number[] { function findMacros(input: string, name: MacroName): MacroMatch[] { // eslint-disable-next-line security/detect-non-literal-regexp - const pattern = new RegExp(`\\$__${name}\\b`, 'g'); + const pattern = new RegExp(`\\$\\{?__${name}\\b`, 'g'); const matches: MacroMatch[] = []; for (const match of input.matchAll(pattern)) { @@ -414,13 +429,22 @@ export function replaceMacros( chartConfig: Pick< RawSqlChartConfig, 'sqlTemplate' | 'from' | 'metricTables' | 'variables' - >, + > & + Partial>, filtersSQL?: string, ): string { - const { from, metricTables, variables } = chartConfig; + const { from, metricTables, variables, dateRange, timeZone } = chartConfig; const allMacros: Macro[] = [ ...MACROS, + ...GLOBAL_VARIABLES.map(({ name, minArgs, maxArgs, description }) => ({ + name, + minArgs, + maxArgs, + description, + replace: (args: string[]) => + expandGlobalVariable(name, { dateRange, timeZone, variables }, args), + })), { name: 'filters', minArgs: 0, diff --git a/packages/common-utils/src/types.ts b/packages/common-utils/src/types.ts index d21d64df04..09859ac8ca 100644 --- a/packages/common-utils/src/types.ts +++ b/packages/common-utils/src/types.ts @@ -2065,6 +2065,9 @@ export type DateRange = { // `convertDateRangeToGranularityString`. PromQL also reads it as the // source's scrape interval for `$__rate_interval`. Never persisted. minGranularitySeconds?: number; + // Runtime-only IANA zone the user views times in, read by raw SQL's + // `${__timezone}`. Unset (e.g. alerts) means UTC. Never persisted. + timeZone?: string; }; export type ChartConfigWithDateRange = ChartConfig & DateRange; diff --git a/packages/common-utils/src/variables.ts b/packages/common-utils/src/variables.ts index 9abe461e7c..247643ae01 100644 --- a/packages/common-utils/src/variables.ts +++ b/packages/common-utils/src/variables.ts @@ -225,7 +225,7 @@ export function findBalancedParens(input: string, start: number): number { * * At each `$` the scanner tries, in order: * 1. a known `$__` macro (longest match, requiring a non-word char after the name so `$__filter` never matches the prefix of `$__filters`), - * 2. a `${name}` / `${name:format}` reference, then a + * 2. a known macro in braces, `${__}` / `${__:format}`, then a `${name}` / `${name:format}` reference, then a * 3. bare `$name` reference (maximal munch). Anything else is plain text, and an unknown `$__x` is emitted verbatim. * * `onMalformed` controls what happens when a macro's argument list has no @@ -346,6 +346,26 @@ export function scanTemplateTokens( // Attempt to match a braced `${var}` or `${var:format}` reference if (input.charAt(i + 1) === '{') { const closeIndex = input.indexOf('}', i + 2); // no escaping because variable names can't contain `}` or `\` + + // Grafana's braced macro form, `${__from}` / `${__from:date:iso}`, whose format is the macro's argument + const braced = closeIndex > 0 ? input.slice(i + 2, closeIndex) : ''; + const colon = braced.indexOf(':'); + const bracedMacro = braced.startsWith('__') + ? braced.slice(2, colon < 0 ? undefined : colon) + : undefined; + if (bracedMacro && macroNames.includes(bracedMacro)) { + flushText(); + tokens.push({ + kind: 'macro', + name: bracedMacro, + args: colon < 0 ? [] : [braced.slice(colon + 1)], + raw: input.slice(i, closeIndex + 1), + inStringLiteral, + }); + i = closeIndex + 1; + continue; + } + const match = closeIndex > 0 ? input.slice(i + 2, closeIndex).match(BRACED_REFERENCE_REGEX) @@ -1391,6 +1411,9 @@ export function filterReferencedVariables( config: ChartConfigWithOptDateRange | SavedChartConfig, variables: ChartVariable[], ): ChartVariable[] { + // `${__all_variables}` reads every variable, from the SQL or a link template. + if (/\$\{?__all_variables\b/.test(JSON.stringify(config))) return variables; + let names: string[]; if ('configType' in config && config.configType === 'sql') { names = getReferencedVariableNames(config.sqlTemplate);