Skip to content

Commit bbadc0a

Browse files
committed
feat: Support PromQL dashboard tiles in the external API
1 parent f21bdb8 commit bbadc0a

11 files changed

Lines changed: 595 additions & 56 deletions

File tree

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
'@hyperdx/api': minor
3+
---
4+
5+
feat: Support PromQL dashboard tiles in the external API
6+
7+
`/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.

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,9 @@ export function registerGetDashboard({
5959
if (!dashboard) {
6060
return mcpUserError('Dashboard not found');
6161
}
62-
const externalDashboard = convertToExternalDashboard(dashboard);
62+
const externalDashboard = convertToExternalDashboard(dashboard, {
63+
hidePromqlTiles: true,
64+
});
6365
return {
6466
content: [
6567
{

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,9 @@ export function registerGetDashboardTile({
4141
return mcpUserError('Dashboard not found');
4242
}
4343

44-
const externalDashboard = convertToExternalDashboard(dashboard);
44+
const externalDashboard = convertToExternalDashboard(dashboard, {
45+
hidePromqlTiles: true,
46+
});
4547
const tile = externalDashboard.tiles.find(t => t.id === tileId);
4648
if (!tile) {
4749
return mcpUserError(

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

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -99,8 +99,12 @@ export function registerPatchDashboard({
9999
if (existingIdx === -1) {
100100
// Build a human-readable list of available tile IDs.
101101
// Convert only for the error message (read-only, no write-back).
102-
const externalDashboard =
103-
convertToExternalDashboard(existingDashboard);
102+
const externalDashboard = convertToExternalDashboard(
103+
existingDashboard,
104+
{
105+
hidePromqlTiles: true,
106+
},
107+
);
104108
return mcpUserError(
105109
`Tile not found: ${tileId}. Available tile IDs: ${externalDashboard.tiles.map(t => `${t.id} (${t.name})`).join(', ')}`,
106110
);

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,9 @@ export function registerQueryTile({
6666
return mcpUserError('Dashboard not found');
6767
}
6868

69-
const externalDashboard = convertToExternalDashboard(dashboard);
69+
const externalDashboard = convertToExternalDashboard(dashboard, {
70+
hidePromqlTiles: true,
71+
});
7072
const tile = externalDashboard.tiles.find(t => t.id === tileId);
7173
if (!tile) {
7274
return mcpUserError(

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -221,7 +221,9 @@ export function registerQueryTiles({
221221
return mcpUserError('Dashboard not found');
222222
}
223223

224-
const externalDashboard = convertToExternalDashboard(dashboard);
224+
const externalDashboard = convertToExternalDashboard(dashboard, {
225+
hidePromqlTiles: true,
226+
});
225227
const allTiles = externalDashboard.tiles;
226228

227229
const resolved = resolveDashboardVariables(

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

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -212,7 +212,9 @@ async function createDashboard({
212212

213213
recordDashboardOnboardingIfHasTiles(userId, newDashboard.tiles);
214214

215-
const externalDashboard = convertToExternalDashboard(newDashboard);
215+
const externalDashboard = convertToExternalDashboard(newDashboard, {
216+
hidePromqlTiles: true,
217+
});
216218
return {
217219
content: [
218220
{
@@ -377,7 +379,9 @@ async function updateDashboard({
377379

378380
recordDashboardOnboardingIfHasTiles(userId, updatedDashboard.tiles);
379381

380-
const externalDashboard = convertToExternalDashboard(updatedDashboard);
382+
const externalDashboard = convertToExternalDashboard(updatedDashboard, {
383+
hidePromqlTiles: true,
384+
});
381385
return {
382386
content: [
383387
{

‎packages/api/src/routers/external-api/__tests__/dashboards.int.test.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7183,10 +7183,12 @@ describe('External API v2 Dashboards - new format', () => {
71837183
// check it would persist as a builder tile AND skip the builder-only
71847184
// rules — here a formula referencing a nonexistent series.
71857185
const res = await postTile({
7186-
configType: 'promql',
7186+
configType: 'foo',
71877187
formulas: [{ expression: 'C * 2' }],
71887188
}).expect(400);
7189-
expect(res.body.message).toContain('configType must be "sql" or omitted');
7189+
expect(res.body.message).toContain(
7190+
'configType must be "sql", "promql" or omitted',
7191+
);
71907192
});
71917193

71927194
it('round-trips formulas on a log/trace event source', async () => {

‎packages/api/src/routers/external-api/v2/utils/__tests__/dashboards.test.ts‎

Lines changed: 216 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,12 @@ import {
33
validateDashboardTileContainerRefs,
44
} from '@hyperdx/common-utils/dist/dashboardValidation';
55
import { isBuilderSavedChartConfig } from '@hyperdx/common-utils/dist/guards';
6-
import { DisplayType, MetricsDataType } from '@hyperdx/common-utils/dist/types';
6+
import {
7+
DisplayType,
8+
MetricsDataType,
9+
PromqlReducer,
10+
PromqlSavedChartConfig,
11+
} from '@hyperdx/common-utils/dist/types';
712
import mongoose from 'mongoose';
813
import { z } from 'zod';
914

@@ -13,8 +18,13 @@ import {
1318
ConfigTile,
1419
convertToExternalDashboard,
1520
convertToInternalTileConfig,
21+
isConfigTile,
1622
} from '@/routers/external-api/v2/utils/dashboards';
17-
import { externalDashboardSelectItemSchema } from '@/utils/zod';
23+
import {
24+
externalAlertChartConfigSchema,
25+
externalDashboardSelectItemSchema,
26+
externalDashboardTileSchemaWithId,
27+
} from '@/utils/zod';
1828

1929
function makeMarkdownTile(
2030
markdown?: string,
@@ -383,24 +393,31 @@ describe('convertToExternalDashboard orphan-ref heal', () => {
383393
expect(ext.tiles[0].tabId).toBe('errors');
384394
});
385395

386-
it('drops PromQL tiles from external response (no schema variant yet)', () => {
396+
it('returns PromQL tiles unless hidePromqlTiles is set', () => {
387397
const doc = makeDoc({
388398
tiles: [
389399
makeTile({
390400
id: 'promql-tile',
391401
config: {
392402
configType: 'promql',
393403
promqlExpression: 'up',
394-
connection: 'conn-1',
404+
source: new mongoose.Types.ObjectId().toString(),
395405
displayType: DisplayType.Line,
396406
name: 'My PromQL tile',
397-
} as any,
407+
},
398408
}),
399409
makeTile({ id: 'normal-tile' }),
400410
],
401411
});
402-
const ext = convertToExternalDashboard(doc);
403-
expect(ext.tiles.map(t => t.id)).toEqual(['normal-tile']);
412+
expect(convertToExternalDashboard(doc).tiles.map(t => t.id)).toEqual([
413+
'promql-tile',
414+
'normal-tile',
415+
]);
416+
expect(
417+
convertToExternalDashboard(doc, { hidePromqlTiles: true }).tiles.map(
418+
t => t.id,
419+
),
420+
).toEqual(['normal-tile']);
404421
});
405422

406423
// seriesLimit is three-state (matching the internal schema): omitted =
@@ -628,3 +645,195 @@ describe('externalDashboardSelectItemSchema metric selects', () => {
628645
);
629646
});
630647
});
648+
649+
describe('PromQL tiles', () => {
650+
const source = new mongoose.Types.ObjectId().toString();
651+
652+
function readPromqlTile(config: Record<string, unknown>) {
653+
const doc = makeDoc({ tiles: [makeTile({ id: 'promql-tile', config })] });
654+
return convertToExternalDashboard(doc).tiles[0];
655+
}
656+
657+
function parseTile(tile: unknown) {
658+
const parsed = externalDashboardTileSchemaWithId.parse(
659+
JSON.parse(JSON.stringify(tile)),
660+
);
661+
if (!isConfigTile(parsed)) throw new Error('expected a config tile');
662+
return parsed;
663+
}
664+
665+
const base = {
666+
configType: 'promql',
667+
name: 'PromQL tile',
668+
source,
669+
granularity: '5 minute',
670+
numberFormat: { output: 'number' },
671+
} as const;
672+
673+
it.each<[string, PromqlSavedChartConfig]>([
674+
[
675+
'line',
676+
{
677+
...base,
678+
displayType: DisplayType.Line,
679+
promqlExpression: [
680+
{ expression: 'up', alias: 'Up' },
681+
{ expression: 'rate(errors_total[$__rate_interval])' },
682+
],
683+
legendTemplate: '{{job}}',
684+
fillNulls: false,
685+
alignDateRangeToGranularity: true,
686+
compareToPreviousPeriod: true,
687+
seriesLimit: 0,
688+
},
689+
],
690+
[
691+
'stacked bar',
692+
{
693+
...base,
694+
displayType: DisplayType.StackedBar,
695+
promqlExpression: [{ expression: 'up' }],
696+
legendTemplate: '{{job}}',
697+
seriesLimit: 5,
698+
},
699+
],
700+
[
701+
'table',
702+
{
703+
...base,
704+
displayType: DisplayType.Table,
705+
promqlExpression: [{ expression: 'up', queryType: 'instant' }],
706+
},
707+
],
708+
[
709+
'number',
710+
{
711+
...base,
712+
displayType: DisplayType.Number,
713+
promqlExpression: [
714+
{ expression: 'up', queryType: 'range', reducer: PromqlReducer.Max },
715+
],
716+
color: 'chart-blue',
717+
colorRules: [{ operator: 'gt', value: 5, color: 'chart-red' }],
718+
backgroundChart: { type: 'area' },
719+
},
720+
],
721+
[
722+
'pie',
723+
{
724+
...base,
725+
displayType: DisplayType.Pie,
726+
promqlExpression: [{ expression: 'up', reducer: PromqlReducer.Sum }],
727+
legendTemplate: '{{job}}',
728+
seriesLimit: 3,
729+
},
730+
],
731+
[
732+
'heatmap',
733+
{
734+
...base,
735+
displayType: DisplayType.Heatmap,
736+
promqlExpression: [{ expression: 'sum by (le) (rate(x_bucket[5m]))' }],
737+
heatmap: { mode: 'histogram', scaleType: 'linear' },
738+
},
739+
],
740+
])('round-trips a %s tile through GET and PUT', (_label, config) => {
741+
const tile = parseTile(readPromqlTile(config));
742+
expect(convertToInternalTileConfig(tile).config).toEqual(config);
743+
});
744+
745+
it('reads a single-string expression as a one-item list', () => {
746+
const tile = readPromqlTile({
747+
...base,
748+
displayType: DisplayType.Line,
749+
promqlExpression: 'up',
750+
});
751+
expect(tile.config).toMatchObject({ expressions: [{ expression: 'up' }] });
752+
expect(convertToInternalTileConfig(parseTile(tile)).config).toMatchObject({
753+
promqlExpression: [{ expression: 'up' }],
754+
});
755+
});
756+
757+
it('does not expose or persist a stored connection', () => {
758+
const tile = readPromqlTile({
759+
...base,
760+
displayType: DisplayType.Line,
761+
promqlExpression: 'up',
762+
connection: 'conn-1',
763+
});
764+
expect(JSON.stringify(tile)).not.toContain('conn-1');
765+
expect(
766+
convertToInternalTileConfig(parseTile(tile)).config,
767+
).not.toHaveProperty('connection');
768+
});
769+
770+
it('drops expression options the display type does not offer', () => {
771+
const tile = parseTile({
772+
id: 'promql-tile',
773+
name: 'PromQL tile',
774+
x: 0,
775+
y: 0,
776+
w: 6,
777+
h: 4,
778+
config: {
779+
configType: 'promql',
780+
displayType: 'line',
781+
sourceId: source,
782+
expressions: [
783+
{ expression: 'up', queryType: 'instant', reducer: 'max' },
784+
],
785+
},
786+
});
787+
expect(tile.config).toMatchObject({ expressions: [{ expression: 'up' }] });
788+
expect(tile.config).not.toHaveProperty('expressions.0.queryType');
789+
});
790+
791+
describe('schema', () => {
792+
const tile = (config: Record<string, unknown>) => ({
793+
id: 'promql-tile',
794+
name: 'PromQL tile',
795+
x: 0,
796+
y: 0,
797+
w: 6,
798+
h: 4,
799+
config: {
800+
configType: 'promql',
801+
displayType: 'line',
802+
sourceId: source,
803+
expressions: [{ expression: 'up' }],
804+
...config,
805+
},
806+
});
807+
808+
it.each([
809+
['no sourceId', { sourceId: undefined }],
810+
['no expressions', { expressions: [] }],
811+
[
812+
'more than 10 expressions',
813+
{ expressions: Array(11).fill({ expression: 'up' }) },
814+
],
815+
['an unsupported display type', { displayType: 'search' }],
816+
['an invalid granularity', { granularity: '5m' }],
817+
])('rejects a tile with %s', (_label, config) => {
818+
expect(
819+
externalDashboardTileSchemaWithId.safeParse(tile(config)).success,
820+
).toBe(false);
821+
});
822+
823+
it('rejects an unknown configType', () => {
824+
const result = externalDashboardTileSchemaWithId.safeParse(
825+
tile({ configType: 'foo' }),
826+
);
827+
expect(result.error?.issues[0].message).toBe(
828+
'configType must be "sql", "promql" or omitted (builder configs carry no configType)',
829+
);
830+
});
831+
832+
it('is not accepted as an inline alert config', () => {
833+
const result = externalAlertChartConfigSchema.safeParse(tile({}).config);
834+
expect(result.error?.issues[0].message).toBe(
835+
'configType must be "sql" or omitted (builder configs carry no configType)',
836+
);
837+
});
838+
});
839+
});

0 commit comments

Comments
 (0)