diff --git a/.changeset/external-api-promql-tiles.md b/.changeset/external-api-promql-tiles.md new file mode 100644 index 0000000000..1ca68d292a --- /dev/null +++ b/.changeset/external-api-promql-tiles.md @@ -0,0 +1,7 @@ +--- +'@hyperdx/api': minor +--- + +feat: Support PromQL dashboard tiles in the external API + +`/api/v2/dashboards` now returns PromQL tiles and accepts them on create and update, as `configType: "promql"` with a `sourceId` and a list of `expressions`. Previously PromQL tiles were left out of responses, so saving a dashboard back through the API deleted them. MCP dashboard tools still hide PromQL tiles until they support editing them. diff --git a/packages/api/src/mcp/tools/dashboards/getDashboard.ts b/packages/api/src/mcp/tools/dashboards/getDashboard.ts index 278e0f5339..e5eac6714c 100644 --- a/packages/api/src/mcp/tools/dashboards/getDashboard.ts +++ b/packages/api/src/mcp/tools/dashboards/getDashboard.ts @@ -60,7 +60,9 @@ export function registerGetDashboard({ if (!dashboard) { return mcpUserError('Dashboard not found'); } - const externalDashboard = convertToExternalDashboard(dashboard); + const externalDashboard = convertToExternalDashboard(dashboard, { + hidePromqlTiles: true, + }); return { content: [ { diff --git a/packages/api/src/mcp/tools/dashboards/getDashboardTile.ts b/packages/api/src/mcp/tools/dashboards/getDashboardTile.ts index 43230b4290..0857a8b5e2 100644 --- a/packages/api/src/mcp/tools/dashboards/getDashboardTile.ts +++ b/packages/api/src/mcp/tools/dashboards/getDashboardTile.ts @@ -48,7 +48,9 @@ export function registerGetDashboardTile({ return mcpUserError('Dashboard not found'); } - const externalDashboard = convertToExternalDashboard(dashboard); + const externalDashboard = convertToExternalDashboard(dashboard, { + hidePromqlTiles: true, + }); const tile = externalDashboard.tiles.find(t => t.id === tileId); if (!tile) { return mcpUserError( diff --git a/packages/api/src/mcp/tools/dashboards/patchDashboard.ts b/packages/api/src/mcp/tools/dashboards/patchDashboard.ts index d966571acd..77b6f53ba3 100644 --- a/packages/api/src/mcp/tools/dashboards/patchDashboard.ts +++ b/packages/api/src/mcp/tools/dashboards/patchDashboard.ts @@ -104,8 +104,12 @@ export function registerPatchDashboard({ if (existingIdx === -1) { // Build a human-readable list of available tile IDs. // Convert only for the error message (read-only, no write-back). - const externalDashboard = - convertToExternalDashboard(existingDashboard); + const externalDashboard = convertToExternalDashboard( + existingDashboard, + { + hidePromqlTiles: true, + }, + ); return mcpUserError( `Tile not found: ${tileId}. Available tile IDs: ${externalDashboard.tiles.map(t => `${t.id} (${t.name})`).join(', ')}`, ); diff --git a/packages/api/src/mcp/tools/dashboards/queryTile.ts b/packages/api/src/mcp/tools/dashboards/queryTile.ts index c05153c190..0ef97eb39d 100644 --- a/packages/api/src/mcp/tools/dashboards/queryTile.ts +++ b/packages/api/src/mcp/tools/dashboards/queryTile.ts @@ -75,7 +75,9 @@ export function registerQueryTile({ return mcpUserError('Dashboard not found'); } - const externalDashboard = convertToExternalDashboard(dashboard); + const externalDashboard = convertToExternalDashboard(dashboard, { + hidePromqlTiles: true, + }); const tile = externalDashboard.tiles.find(t => t.id === tileId); if (!tile) { return mcpUserError( diff --git a/packages/api/src/mcp/tools/dashboards/queryTiles.ts b/packages/api/src/mcp/tools/dashboards/queryTiles.ts index 443076db76..c0d33ebbda 100644 --- a/packages/api/src/mcp/tools/dashboards/queryTiles.ts +++ b/packages/api/src/mcp/tools/dashboards/queryTiles.ts @@ -224,7 +224,9 @@ export function registerQueryTiles({ return mcpUserError('Dashboard not found'); } - const externalDashboard = convertToExternalDashboard(dashboard); + const externalDashboard = convertToExternalDashboard(dashboard, { + hidePromqlTiles: true, + }); const allTiles = externalDashboard.tiles; const resolved = resolveDashboardVariables( diff --git a/packages/api/src/mcp/tools/dashboards/saveDashboard.ts b/packages/api/src/mcp/tools/dashboards/saveDashboard.ts index 477f55d692..827f56f66a 100644 --- a/packages/api/src/mcp/tools/dashboards/saveDashboard.ts +++ b/packages/api/src/mcp/tools/dashboards/saveDashboard.ts @@ -208,7 +208,9 @@ async function createDashboard({ recordDashboardOnboardingIfHasTiles(userId, newDashboard.tiles); - const externalDashboard = convertToExternalDashboard(newDashboard); + const externalDashboard = convertToExternalDashboard(newDashboard, { + hidePromqlTiles: true, + }); return { content: [ { @@ -373,7 +375,9 @@ async function updateDashboard({ recordDashboardOnboardingIfHasTiles(userId, updatedDashboard.tiles); - const externalDashboard = convertToExternalDashboard(updatedDashboard); + const externalDashboard = convertToExternalDashboard(updatedDashboard, { + hidePromqlTiles: true, + }); return { content: [ { diff --git a/packages/api/src/routers/external-api/__tests__/dashboards.int.test.ts b/packages/api/src/routers/external-api/__tests__/dashboards.int.test.ts index 5e4e55d087..d579706d49 100644 --- a/packages/api/src/routers/external-api/__tests__/dashboards.int.test.ts +++ b/packages/api/src/routers/external-api/__tests__/dashboards.int.test.ts @@ -5602,6 +5602,71 @@ describe('External API v2 Dashboards - new format', () => { expect(await Alert.findById(alert._id)).toBeNull(); }); + it('should delete alert when tile is updated from builder to PromQL config', async () => { + const tileId = new ObjectId().toString(); + const dashboard = await createTestDashboard({ + tiles: [ + { + id: tileId, + x: 0, + y: 0, + w: 6, + h: 3, + config: { + name: 'Builder Tile', + displayType: 'line', + source: traceSource._id.toString(), + select: [ + { aggFn: 'count', aggCondition: '', valueExpression: '' }, + ], + where: '', + }, + }, + ], + }); + const webhook = await Webhook.create({ + name: 'Test Webhook', + service: WebhookService.Slack, + url: 'https://hooks.slack.com/test', + team: team._id, + }); + const alert = await Alert.create({ + team: team._id, + dashboard: dashboard._id, + tileId, + source: AlertSource.TILE, + threshold: 100, + interval: '1h', + thresholdType: AlertThresholdType.ABOVE, + channel: { type: 'webhook', webhookId: webhook._id.toString() }, + }); + + await authRequest('put', `${BASE_URL}/${dashboard._id}`) + .send({ + name: 'Updated Dashboard', + tags: [], + tiles: [ + { + id: tileId, + name: 'PromQL Tile', + x: 0, + y: 0, + w: 6, + h: 3, + config: { + configType: 'promql', + displayType: 'line', + sourceId: promqlSource._id.toString(), + expressions: [{ expression: 'up' }], + }, + }, + ], + }) + .expect(200); + + expect(await Alert.findById(alert._id)).toBeNull(); + }); + it('should delete alert when a tile with an alert is removed from the dashboard', async () => { const keepTileId = new ObjectId().toString(); const removeTileId = new ObjectId().toString(); @@ -7255,10 +7320,12 @@ describe('External API v2 Dashboards - new format', () => { // check it would persist as a builder tile AND skip the builder-only // rules — here a formula referencing a nonexistent series. const res = await postTile({ - configType: 'promql', + configType: 'foo', formulas: [{ expression: 'C * 2' }], }).expect(400); - expect(res.body.message).toContain('configType must be "sql" or omitted'); + expect(res.body.message).toContain( + 'configType must be "sql", "promql" or omitted', + ); }); it('round-trips formulas on a log/trace event source', async () => { diff --git a/packages/api/src/routers/external-api/v2/utils/__tests__/dashboards.test.ts b/packages/api/src/routers/external-api/v2/utils/__tests__/dashboards.test.ts index 2dca4ef17e..f66ce964fc 100644 --- a/packages/api/src/routers/external-api/v2/utils/__tests__/dashboards.test.ts +++ b/packages/api/src/routers/external-api/v2/utils/__tests__/dashboards.test.ts @@ -3,7 +3,12 @@ import { validateDashboardTileContainerRefs, } from '@hyperdx/common-utils/dist/dashboardValidation'; import { isBuilderSavedChartConfig } from '@hyperdx/common-utils/dist/guards'; -import { DisplayType, MetricsDataType } from '@hyperdx/common-utils/dist/types'; +import { + DisplayType, + MetricsDataType, + PromqlReducer, + PromqlSavedChartConfig, +} from '@hyperdx/common-utils/dist/types'; import mongoose from 'mongoose'; import { z } from 'zod'; @@ -14,9 +19,12 @@ import { convertExternalTilesToInternal, convertToExternalDashboard, convertToInternalTileConfig, + isConfigTile, } from '@/routers/external-api/v2/utils/dashboards'; import { + externalAlertChartConfigSchema, externalDashboardSelectItemSchema, + externalDashboardTileSchemaWithId, ExternalDashboardTileWithId, } from '@/utils/zod'; @@ -453,7 +461,7 @@ describe('convertToExternalDashboard orphan-ref heal', () => { expect(ext.tiles[0].tabId).toBe('errors'); }); - it('drops PromQL tiles from external response (no schema variant yet)', () => { + it('returns PromQL tiles unless hidePromqlTiles is set', () => { const doc = makeDoc({ tiles: [ makeTile({ @@ -461,16 +469,23 @@ describe('convertToExternalDashboard orphan-ref heal', () => { config: { configType: 'promql', promqlExpression: 'up', - connection: 'conn-1', + source: new mongoose.Types.ObjectId().toString(), displayType: DisplayType.Line, name: 'My PromQL tile', - } as any, + }, }), makeTile({ id: 'normal-tile' }), ], }); - const ext = convertToExternalDashboard(doc); - expect(ext.tiles.map(t => t.id)).toEqual(['normal-tile']); + expect(convertToExternalDashboard(doc).tiles.map(t => t.id)).toEqual([ + 'promql-tile', + 'normal-tile', + ]); + expect( + convertToExternalDashboard(doc, { hidePromqlTiles: true }).tiles.map( + t => t.id, + ), + ).toEqual(['normal-tile']); }); // seriesLimit is three-state (matching the internal schema): omitted = @@ -698,3 +713,206 @@ describe('externalDashboardSelectItemSchema metric selects', () => { ); }); }); + +describe('PromQL tiles', () => { + const source = new mongoose.Types.ObjectId().toString(); + + function readPromqlTile(config: Record) { + const doc = makeDoc({ tiles: [makeTile({ id: 'promql-tile', config })] }); + return convertToExternalDashboard(doc).tiles[0]; + } + + function parseTile(tile: unknown) { + const parsed = externalDashboardTileSchemaWithId.parse( + JSON.parse(JSON.stringify(tile)), + ); + if (!isConfigTile(parsed)) throw new Error('expected a config tile'); + return parsed; + } + + const base = { + configType: 'promql', + name: 'PromQL tile', + source, + granularity: '5 minute', + numberFormat: { output: 'number' }, + } as const; + + it.each<[string, PromqlSavedChartConfig]>([ + [ + 'line', + { + ...base, + displayType: DisplayType.Line, + promqlExpression: [ + { expression: 'up', alias: 'Up' }, + { expression: 'rate(errors_total[$__rate_interval])' }, + ], + description: 'Targets that are up', + legendTemplate: '{{job}}', + fillNulls: false, + alignDateRangeToGranularity: true, + compareToPreviousPeriod: true, + lineInterpolation: 'step', + seriesLimit: 0, + }, + ], + [ + 'stacked line', + { + ...base, + displayType: DisplayType.StackedLine, + promqlExpression: [{ expression: 'up' }], + lineInterpolation: 'smooth', + }, + ], + [ + 'stacked bar', + { + ...base, + displayType: DisplayType.StackedBar, + promqlExpression: [{ expression: 'up' }], + legendTemplate: '{{job}}', + seriesLimit: 5, + }, + ], + [ + 'table', + { + ...base, + displayType: DisplayType.Table, + promqlExpression: [{ expression: 'up', queryType: 'instant' }], + }, + ], + [ + 'number', + { + ...base, + displayType: DisplayType.Number, + promqlExpression: [ + { expression: 'up', queryType: 'range', reducer: PromqlReducer.Max }, + ], + color: 'chart-blue', + colorRules: [{ operator: 'gt', value: 5, color: 'chart-red' }], + backgroundChart: { type: 'area' }, + }, + ], + [ + 'pie', + { + ...base, + displayType: DisplayType.Pie, + promqlExpression: [{ expression: 'up', reducer: PromqlReducer.Sum }], + legendTemplate: '{{job}}', + seriesLimit: 3, + }, + ], + [ + 'heatmap', + { + ...base, + displayType: DisplayType.Heatmap, + promqlExpression: [{ expression: 'sum by (le) (rate(x_bucket[5m]))' }], + heatmap: { mode: 'histogram', scaleType: 'linear' }, + }, + ], + ])('round-trips a %s tile through GET and PUT', (_label, config) => { + const tile = parseTile(readPromqlTile(config)); + expect(convertToInternalTileConfig(tile).config).toEqual(config); + }); + + it('reads a single-string expression as a one-item list', () => { + const tile = readPromqlTile({ + ...base, + displayType: DisplayType.Line, + promqlExpression: 'up', + }); + expect(tile.config).toMatchObject({ expressions: [{ expression: 'up' }] }); + expect(convertToInternalTileConfig(parseTile(tile)).config).toMatchObject({ + promqlExpression: [{ expression: 'up' }], + }); + }); + + it('does not expose or persist a stored connection', () => { + const tile = readPromqlTile({ + ...base, + displayType: DisplayType.Line, + promqlExpression: 'up', + connection: 'conn-1', + }); + expect(JSON.stringify(tile)).not.toContain('conn-1'); + expect( + convertToInternalTileConfig(parseTile(tile)).config, + ).not.toHaveProperty('connection'); + }); + + it('drops expression options the display type does not offer', () => { + const tile = parseTile({ + id: 'promql-tile', + name: 'PromQL tile', + x: 0, + y: 0, + w: 6, + h: 4, + config: { + configType: 'promql', + displayType: 'line', + sourceId: source, + expressions: [ + { expression: 'up', queryType: 'instant', reducer: 'max' }, + ], + }, + }); + expect(tile.config).toMatchObject({ expressions: [{ expression: 'up' }] }); + expect(tile.config).not.toHaveProperty('expressions.0.queryType'); + }); + + describe('schema', () => { + const tile = (config: Record) => ({ + id: 'promql-tile', + name: 'PromQL tile', + x: 0, + y: 0, + w: 6, + h: 4, + config: { + configType: 'promql', + displayType: 'line', + sourceId: source, + expressions: [{ expression: 'up' }], + ...config, + }, + }); + + it.each([ + ['no sourceId', { sourceId: undefined }], + ['no expressions', { expressions: [] }], + [ + 'more than 10 expressions', + { expressions: Array(11).fill({ expression: 'up' }) }, + ], + ['an unsupported display type', { displayType: 'search' }], + ['an invalid granularity', { granularity: '5m' }], + ])('rejects a tile with %s', (_label, config) => { + expect( + externalDashboardTileSchemaWithId.safeParse(tile(config)).success, + ).toBe(false); + }); + + it('rejects an unknown configType', () => { + const result = externalDashboardTileSchemaWithId.safeParse( + tile({ configType: 'foo' }), + ); + expect(result.error?.issues[0].message).toBe( + 'configType must be "sql", "promql" or omitted (builder configs carry no configType)', + ); + }); + + it('is not accepted as an inline alert config', () => { + const result = externalAlertChartConfigSchema.safeParse(tile({}).config); + expect(result.error?.issues[0].message).toBe( + 'configType must be "sql" or omitted (builder configs carry no configType)', + ); + }); + }); +}); diff --git a/packages/api/src/routers/external-api/v2/utils/dashboards.ts b/packages/api/src/routers/external-api/v2/utils/dashboards.ts index 47bf79d4f6..5f26c518c3 100644 --- a/packages/api/src/routers/external-api/v2/utils/dashboards.ts +++ b/packages/api/src/routers/external-api/v2/utils/dashboards.ts @@ -1,4 +1,5 @@ import { getHeatmapMode } from '@hyperdx/common-utils/dist/core/heatmap'; +import { getPromqlSeries } from '@hyperdx/common-utils/dist/core/promql'; import { displayTypeSupportsBuilderAlerts, displayTypeSupportsRawSqlAlerts, @@ -39,6 +40,7 @@ import { isTraceSource, NumberTileColorCondition, NumberTileColorConditionSchema, + PromqlSavedChartConfig, RawSqlSavedChartConfig, resolveChartPaletteToken, SavedChartConfig, @@ -62,11 +64,13 @@ import { } from '@/utils/externalApi'; import logger from '@/utils/logger'; import { + ExternalDashboardBuilderTileConfig, ExternalDashboardFilter, externalDashboardFilterSchema, externalDashboardFilterSchemaWithId, ExternalDashboardFilterWithId, ExternalDashboardHeatmapSelectItem, + ExternalDashboardPromqlTileConfig, ExternalDashboardRawSqlTileConfig, externalDashboardSavedFilterValueSchema, ExternalDashboardSelectItem, @@ -99,8 +103,20 @@ export function isRawSqlExternalTileConfig( return 'configType' in config && config.configType === 'sql'; } +function isPromqlExternalTileConfig( + config: ExternalDashboardTileConfig, +): config is ExternalDashboardPromqlTileConfig { + return 'configType' in config && config.configType === 'promql'; +} + +function isBuilderExternalTileConfig( + config: ExternalDashboardTileConfig, +): config is ExternalDashboardBuilderTileConfig { + return !('configType' in config); +} + type ExternalHeatmapTileConfig = Extract< - ExternalDashboardTileConfig, + ExternalDashboardBuilderTileConfig, { displayType: 'heatmap' } >; @@ -223,6 +239,96 @@ const toExternalColorRules = ( return resolved.length > 0 ? resolved : undefined; }; +const convertPromqlConfigToExternal = ( + config: PromqlSavedChartConfig, +): ExternalDashboardPromqlTileConfig => { + const base = { + configType: 'promql' as const, + sourceId: config.source, + granularity: config.granularity, + numberFormat: config.numberFormat, + }; + + const series = getPromqlSeries(config); + const rangeExpressions = series.map(s => pick(s, ['expression', 'alias'])); + const instantExpressions = series.map(s => + pick(s, ['expression', 'alias', 'queryType']), + ); + const reducibleExpressions = series.map(s => + pick(s, ['expression', 'alias', 'queryType', 'reducer']), + ); + const timeChartFields = { + expressions: rangeExpressions, + legendTemplate: config.legendTemplate, + fillNulls: config.fillNulls !== false, + alignDateRangeToGranularity: config.alignDateRangeToGranularity, + seriesLimit: config.seriesLimit ?? undefined, + }; + + switch (config.displayType) { + case DisplayType.StackedBar: + return { ...base, ...timeChartFields, displayType: 'stacked_bar' }; + case DisplayType.StackedLine: + return { + ...base, + ...timeChartFields, + displayType: 'stacked_line', + lineInterpolation: config.lineInterpolation, + }; + case DisplayType.Table: + return { ...base, displayType: 'table', expressions: instantExpressions }; + case DisplayType.Number: + return { + ...base, + displayType: 'number', + expressions: reducibleExpressions, + color: resolveChartPaletteToken(config.color), + colorRules: toExternalColorRules(config.colorRules), + backgroundChart: config.backgroundChart, + }; + case DisplayType.Pie: + case DisplayType.Bar: + return { + ...base, + displayType: config.displayType === DisplayType.Pie ? 'pie' : 'bar', + expressions: reducibleExpressions, + legendTemplate: config.legendTemplate, + limit: config.seriesLimit ?? undefined, + }; + case DisplayType.Heatmap: + return { + ...base, + displayType: 'heatmap', + expressions: rangeExpressions, + heatmapMode: config.heatmap?.mode, + heatmapScaleType: config.heatmap?.scaleType, + legendTemplate: config.legendTemplate, + }; + case DisplayType.Search: + case DisplayType.Markdown: + case DisplayType.EventPatterns: + // The editor never saves these for PromQL. Emitting a line chart keeps + // the tile a PromQL tile on a GET -> PUT round-trip. + logger.error( + { displayType: config.displayType }, + 'PromQL tile has an unsupported display type; emitting it as a line chart', + ); + break; + case DisplayType.Line: + case undefined: + break; + default: + config.displayType satisfies never; + } + return { + ...base, + ...timeChartFields, + displayType: 'line', + compareToPreviousPeriod: config.compareToPreviousPeriod, + lineInterpolation: config.lineInterpolation, + }; +}; + // Exported for the inline-alert converter (v2/utils/alertChartConfig.ts), // which reuses the tile-config translation for an alert's persisted config. export const convertToExternalTileChartConfig = ( @@ -324,9 +430,8 @@ export const convertToExternalTileChartConfig = ( return undefined; } - // PromQL configs are not yet supported in the external API if (isPromqlSavedChartConfig(config)) { - return undefined; + return convertPromqlConfigToExternal(config); } const sourceId = config.source?.toString() ?? ''; @@ -583,19 +688,7 @@ function convertTileToExternalChart( tile: DashboardDocument['tiles'][number], containerById: Map, dashboardId: string, -): ExternalDashboardTileWithId | undefined { - // PromQL tiles have no external schema representation yet. Dropping them on - // read (and letting the caller filter undefined) is safer than falling - // through to defaultTileConfig — that would silently overwrite the PromQL - // config with an empty Line tile on a GET → PUT round-trip. - if (isPromqlSavedChartConfig(tile.config)) { - logger.warn( - { dashboardId, tileId: tile.id }, - 'Skipping PromQL tile in external API response (not yet supported)', - ); - return undefined; - } - +): ExternalDashboardTileWithId { // Returned in case of a failure converting the saved chart config const defaultTileConfig: ExternalDashboardTileConfig = isRawSqlSavedChartConfig(tile.config) @@ -679,6 +772,13 @@ function convertTileToExternalChart( export function convertToExternalDashboard( dashboard: DashboardDocument, + { + hidePromqlTiles = false, + }: { + // MCP cannot save PromQL tiles until HDX-5302, so its tools hide them + // rather than show tiles the agent cannot edit. Remove with that work. + hidePromqlTiles?: boolean; + } = {}, ): ExternalDashboard { const containers = dashboard.containers ?? []; // Dedupe by id when building the lookup map: a doc with duplicate @@ -694,8 +794,12 @@ export function convertToExternalDashboard( id: dashboardId, name: dashboard.name, tiles: dashboard.tiles - .map(tile => convertTileToExternalChart(tile, containerById, dashboardId)) - .filter(t => t !== undefined), + .filter( + tile => !(hidePromqlTiles && isPromqlSavedChartConfig(tile.config)), + ) + .map(tile => + convertTileToExternalChart(tile, containerById, dashboardId), + ), tags: dashboard.tags || [], filters: getExternalCompatibleFilters(dashboard.filters).map( translateFilterToExternalFilter, @@ -740,6 +844,79 @@ const convertToInternalSelectItem = ( }; }; +const convertExternalPromqlConfigToInternal = ( + config: ExternalDashboardPromqlTileConfig, + name: string, + description: string | undefined, +): PromqlSavedChartConfig => { + const base = { + configType: 'promql' as const, + name, + description, + source: config.sourceId, + promqlExpression: config.expressions, + granularity: config.granularity, + numberFormat: config.numberFormat, + }; + + switch (config.displayType) { + case 'line': + case 'stacked_bar': + case 'stacked_line': + return { + ...base, + ...pick(config, [ + 'legendTemplate', + 'alignDateRangeToGranularity', + 'seriesLimit', + ]), + displayType: TIME_SERIES_DISPLAY_TYPE_BY_NAME[config.displayType], + fillNulls: config.fillNulls === false ? false : undefined, + compareToPreviousPeriod: + config.displayType === 'line' + ? config.compareToPreviousPeriod + : undefined, + lineInterpolation: + config.displayType === 'stacked_bar' + ? undefined + : config.lineInterpolation, + }; + case 'table': + return { ...base, displayType: DisplayType.Table }; + case 'number': + return { + ...base, + ...pick(config, ['color', 'colorRules', 'backgroundChart']), + displayType: DisplayType.Number, + }; + case 'pie': + case 'bar': + return { + ...base, + displayType: + config.displayType === 'pie' ? DisplayType.Pie : DisplayType.Bar, + legendTemplate: config.legendTemplate, + seriesLimit: config.limit, + }; + case 'heatmap': + return { + ...base, + displayType: DisplayType.Heatmap, + legendTemplate: config.legendTemplate, + ...(config.heatmapMode || config.heatmapScaleType + ? { + heatmap: { + ...(config.heatmapMode ? { mode: config.heatmapMode } : {}), + ...(config.heatmapScaleType + ? { scaleType: config.heatmapScaleType } + : {}), + }, + } + : {}), + }; + } +}; + export function convertToInternalTileConfig( externalTile: ConfigTile, ): DashboardDocument['tiles'][number] { @@ -749,7 +926,13 @@ export function convertToInternalTileConfig( let internalConfig: SavedChartConfig; - if (isRawSqlExternalTileConfig(externalConfig)) { + if (isPromqlExternalTileConfig(externalConfig)) { + internalConfig = convertExternalPromqlConfigToInternal( + externalConfig, + name, + description, + ); + } else if (isRawSqlExternalTileConfig(externalConfig)) { switch (externalConfig.displayType) { case 'line': case 'stacked_bar': @@ -1159,7 +1342,7 @@ function getHeatmapTilesWithIncompatibleSources( for (const tile of tiles) { if ( !isConfigTile(tile) || - isRawSqlExternalTileConfig(tile.config) || + !isBuilderExternalTileConfig(tile.config) || tile.config.displayType !== 'heatmap' || !tile.config.sourceId ) { @@ -1207,7 +1390,7 @@ function getFormulaTilesWithIncompatibleSources( for (const tile of tiles) { if ( isConfigTile(tile) && - !isRawSqlExternalTileConfig(tile.config) && + isBuilderExternalTileConfig(tile.config) && 'formulas' in tile.config && (tile.config.formulas?.length ?? 0) > 0 && 'sourceId' in tile.config && @@ -1245,7 +1428,7 @@ function filterChangedFormulaTiles( return requestTiles.filter(tile => { if ( !isConfigTile(tile) || - isRawSqlExternalTileConfig(tile.config) || + !isBuilderExternalTileConfig(tile.config) || !('formulas' in tile.config) || (tile.config.formulas?.length ?? 0) === 0 ) { @@ -1293,7 +1476,7 @@ function filterChangedHeatmapTiles( return requestTiles.filter(tile => { if ( !isConfigTile(tile) || - isRawSqlExternalTileConfig(tile.config) || + !isBuilderExternalTileConfig(tile.config) || tile.config.displayType !== 'heatmap' ) { return false; @@ -1642,9 +1825,14 @@ export async function cleanupDashboardAlerts({ }) { const newTileIdSet = new Set(internalTiles.map(t => t.id)); const tileIdsToDeleteAlerts = [ - // Tiles whose config no longer supports alerts (raw SQL or builder). + // Tiles whose config no longer supports alerts. PromQL tiles cannot be + // alerted on (HDX-4636), so an alert left on a tile switched to PromQL + // would never be checked. ...internalTiles .filter(tile => { + if (isPromqlSavedChartConfig(tile.config)) { + return true; + } if (isRawSqlSavedChartConfig(tile.config)) { return !displayTypeSupportsRawSqlAlerts(tile.config.displayType); } diff --git a/packages/api/src/utils/zod.ts b/packages/api/src/utils/zod.ts index 8c80e11489..8ec394afdf 100644 --- a/packages/api/src/utils/zod.ts +++ b/packages/api/src/utils/zod.ts @@ -11,7 +11,10 @@ import { ChartPaletteTokenSchema, DASHBOARD_CONTAINER_ID_MAX, DASHBOARD_MAX_TILES, + HeatmapScaleTypeSchema, LineInterpolationSchema, + MAX_LEGEND_TEMPLATE_LENGTH, + MAX_PROMQL_EXPRESSIONS, MetricFormulaSchema, MetricsDataType, NumberFormatSchema, @@ -19,10 +22,14 @@ import { OnClickDashboardSchema, OnClickExternalSchema, OnClickSearchSchema, + PromqlHeatmapModeSchema, PromqlLabelDashboardFilterSchema, + PromqlQueryTypeSchema, + PromqlReducerSchema, QueryExpressionDashboardFilterSchema, scheduleStartAtSchema, SearchConditionLanguageSchema as whereLanguageSchema, + SQLIntervalSchema, StaticListDashboardFilterSchema, tagsSchema, TILE_DESCRIPTION_MAX_LENGTH, @@ -607,7 +614,7 @@ const externalDashboardBuilderTileConfigSchema = z.discriminatedUnion( ], ); -type ExternalDashboardBuilderTileConfig = +export type ExternalDashboardBuilderTileConfig = | z.infer | z.infer; @@ -644,6 +651,118 @@ export type ExternalDashboardRawSqlTileConfig = z.infer< typeof externalDashboardRawSqlTileConfigSchema >; +// PromQL tiles mirror `PromqlSavedChartConfig` (common-utils types.ts) and, +// per display type, the fields the chart editor saves for a PromQL tile +// (`convertFormStateToSavedChartConfig`). `connection` is not exposed: it is +// read from the source at query time. +const externalPromqlRangeExpressionSchema = z.object({ + expression: z.string().max(10000), + alias: z.string().max(10000).optional(), +}); + +// Table, number, pie and bar tiles can evaluate an expression at a single +// instant (`displayTypeSupportsInstantQuery`); other display types drop +// `queryType` like the editor does. +const externalPromqlInstantExpressionSchema = + externalPromqlRangeExpressionSchema.extend({ + queryType: PromqlQueryTypeSchema.optional(), + }); + +// Number, pie and bar tiles reduce a range query to one value per series +// (`displayTypeSupportsReducer`). +const externalPromqlReducibleExpressionSchema = + externalPromqlInstantExpressionSchema.extend({ + reducer: PromqlReducerSchema.optional(), + }); + +const externalPromqlExpressionListSchema = (item: T) => + z.array(item).min(1).max(MAX_PROMQL_EXPRESSIONS); + +const externalPromqlLegendTemplateSchema = z + .string() + .max(MAX_LEGEND_TEMPLATE_LENGTH) + .optional(); + +const externalPromqlChartConfigBaseSchema = z.object({ + configType: z.literal('promql'), + sourceId: objectIdSchema, + // Sets the Prometheus step and `$__interval` of range queries. + granularity: z.union([SQLIntervalSchema, z.literal('auto')]).optional(), + numberFormat: NumberFormatSchema.optional(), +}); + +const externalPromqlStackedChartConfigSchema = + externalPromqlChartConfigBaseSchema.extend({ + displayType: z.literal('stacked_bar'), + expressions: externalPromqlExpressionListSchema( + externalPromqlRangeExpressionSchema, + ), + legendTemplate: externalPromqlLegendTemplateSchema, + fillNulls: z.boolean().optional(), + alignDateRangeToGranularity: z.boolean().optional(), + seriesLimit: z.number().int().nonnegative().optional(), + }); + +const externalPromqlCategoricalChartConfigSchema = + externalPromqlChartConfigBaseSchema.extend({ + displayType: z.literal('pie'), + expressions: externalPromqlExpressionListSchema( + externalPromqlReducibleExpressionSchema, + ), + legendTemplate: externalPromqlLegendTemplateSchema, + // Three-state: omitted = default cap, 0 = unlimited, positive N = top-N. + limit: z.number().int().nonnegative().optional(), + }); + +const externalDashboardPromqlTileConfigSchema = z.discriminatedUnion( + 'displayType', + [ + externalPromqlStackedChartConfigSchema.extend({ + displayType: z.literal('line'), + compareToPreviousPeriod: z.boolean().optional(), + lineInterpolation: LineInterpolationSchema.optional(), + }), + externalPromqlStackedChartConfigSchema, + externalPromqlStackedChartConfigSchema.extend({ + displayType: z.literal('stacked_line'), + lineInterpolation: LineInterpolationSchema.optional(), + }), + externalPromqlChartConfigBaseSchema.extend({ + displayType: z.literal('table'), + expressions: externalPromqlExpressionListSchema( + externalPromqlInstantExpressionSchema, + ), + }), + externalPromqlChartConfigBaseSchema.extend({ + displayType: z.literal('number'), + expressions: externalPromqlExpressionListSchema( + externalPromqlReducibleExpressionSchema, + ), + color: ChartPaletteTokenSchema.optional(), + colorRules: z.array(NumberTileColorConditionSchema).max(10).optional(), + backgroundChart: BackgroundChartSchema.optional(), + }), + externalPromqlCategoricalChartConfigSchema, + externalPromqlCategoricalChartConfigSchema.extend({ + displayType: z.literal('bar'), + }), + externalPromqlChartConfigBaseSchema.extend({ + displayType: z.literal('heatmap'), + expressions: externalPromqlExpressionListSchema( + externalPromqlRangeExpressionSchema, + ), + // An absent mode is 'distribution'. + heatmapMode: PromqlHeatmapModeSchema.optional(), + heatmapScaleType: HeatmapScaleTypeSchema.optional(), + legendTemplate: externalPromqlLegendTemplateSchema, + }), + ], +); + +export type ExternalDashboardPromqlTileConfig = z.infer< + typeof externalDashboardPromqlTileConfigSchema +>; + /** * Routing predicate for the configType-routed config schemas below * (dashboard tiles and inline alert configs): raw SQL configs carry @@ -655,27 +774,36 @@ const isRawSqlRoutedConfig = (data: unknown): boolean => 'configType' in data && data.configType === 'sql'; +// Dashboard tiles only: inline alert configs have no PromQL variant. +const isPromqlRoutedConfig = (data: unknown): boolean => + data !== null && + typeof data === 'object' && + 'configType' in data && + data.configType === 'promql'; + /** * Rejects a `configType` the routing predicate does not recognize. Without - * this, an unknown value (e.g. `configType: 'promql'`) routes to the builder - * union, which strips the unrecognized keys and parses a body that asked for - * something else — so the caller's PromQL config would silently persist as a - * builder config. Returns true when an issue was raised (caller stops). + * this, an unknown value (e.g. `configType: 'promql'` on an alert config) + * routes to the builder union, which strips the unrecognized keys and parses a + * body that asked for something else — so the caller's config would silently + * persist as a builder config. Returns true when an issue was raised (caller + * stops). */ const addUnsupportedConfigTypeIssue = ( data: unknown, ctx: z.RefinementCtx, + supportedConfigTypes: readonly string[], ): boolean => { if ( data !== null && typeof data === 'object' && 'configType' in data && - data.configType !== 'sql' + !supportedConfigTypes.some(type => type === data.configType) ) { + const supported = supportedConfigTypes.map(type => `"${type}"`).join(', '); ctx.addIssue({ code: z.ZodIssueCode.custom, - message: - 'configType must be "sql" or omitted (builder configs carry no configType)', + message: `configType must be ${supported} or omitted (builder configs carry no configType)`, path: ['configType'], }); return true; @@ -741,19 +869,23 @@ const addConfigTypeRoutedIssues = ( const externalDashboardTileConfigSchema = z .custom< - ExternalDashboardRawSqlTileConfig | ExternalDashboardBuilderTileConfig + | ExternalDashboardRawSqlTileConfig + | ExternalDashboardBuilderTileConfig + | ExternalDashboardPromqlTileConfig >() .superRefine((data, ctx) => { - if (addUnsupportedConfigTypeIssue(data, ctx)) { + if (addUnsupportedConfigTypeIssue(data, ctx, ['sql', 'promql'])) { return; } // Route to the correct sub-schema based on configType so Zod's // discriminatedUnion can produce targeted field-level errors rather // than a generic union failure. - const schema = isRawSqlRoutedConfig(data) - ? externalDashboardRawSqlTileConfigSchema - : getExternalBuilderTileConfigSchema(data); + const schema = isPromqlRoutedConfig(data) + ? externalDashboardPromqlTileConfigSchema + : isRawSqlRoutedConfig(data) + ? externalDashboardRawSqlTileConfigSchema + : getExternalBuilderTileConfigSchema(data); const result = schema.safeParse(data); if (!result.success) { @@ -763,6 +895,10 @@ const externalDashboardTileConfigSchema = z return; } + if (isPromqlRoutedConfig(data)) { + return; + } + addConfigTypeRoutedIssues(data, ctx, { numberSelectMessage: 'Number tiles support a single select item unless formulas are used (extra items are formula operands)', @@ -770,8 +906,9 @@ const externalDashboardTileConfigSchema = z }) .transform(data => { // Re-parse through the appropriate sub-schema to strip unknown fields. - // Safe to call .parse() here — superRefine already validated the data, - // so this is guaranteed to succeed. + if (isPromqlRoutedConfig(data)) { + return externalDashboardPromqlTileConfigSchema.parse(data); + } return isRawSqlRoutedConfig(data) ? externalDashboardRawSqlTileConfigSchema.parse(data) : getExternalBuilderTileConfigSchema(data).parse(data); @@ -1016,7 +1153,7 @@ export type ExternalAlertChartConfig = export const externalAlertChartConfigSchema = z .custom() .superRefine((data, ctx) => { - if (addUnsupportedConfigTypeIssue(data, ctx)) { + if (addUnsupportedConfigTypeIssue(data, ctx, ['sql'])) { return; }