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/external-api-promql-tile-validation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@hyperdx/api': patch
---

fix: Reject external API PromQL tiles that reference a non-PromQL source, and keep PromQL tiles when an MCP agent updates a dashboard

`/api/v2/dashboards` now returns a 400 when a PromQL tile's `sourceId` is not a PromQL source. MCP `clickstack_save_dashboard` updates no longer delete the PromQL tiles that MCP hides from agents.
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
import { DisplayType } from '@hyperdx/common-utils/dist/types';
import mongoose from 'mongoose';

import { callTool, getFirstText } from '@/mcp/__tests__/mcpTestUtils';
import Dashboard from '@/models/dashboard';

import { setupDashboardTests } from './setup';

// MCP cannot edit PromQL tiles until HDX-5302, so it hides them on read and
// keeps them on save. Remove with that work.
describe('MCP Dashboard Tools - PromQL tiles', () => {
const ctx = setupDashboardTests();

const promqlTile = {
id: 'promql-tile',
x: 0,
y: 0,
w: 6,
h: 3,
config: {
configType: 'promql',
name: 'PromQL',
displayType: DisplayType.Line,
source: new mongoose.Types.ObjectId().toString(),
promqlExpression: [{ expression: 'up' }],
},
};

const markdownTile = {
id: 'markdown-tile',
x: 6,
y: 0,
w: 6,
h: 3,
config: {
name: 'Notes',
displayType: DisplayType.Markdown,
markdown: 'Notes',
source: '',
where: '',
select: [],
},
};

const createDashboard = () =>
new Dashboard({
name: 'PromQL dashboard',
tiles: [promqlTile, markdownTile],
team: ctx.team._id,
}).save();

it('hides PromQL tiles from clickstack_get_dashboard', async () => {
const dashboard = await createDashboard();

const result = await callTool(ctx.client!, 'clickstack_get_dashboard', {
id: dashboard._id.toString(),
});

expect(result.isError).toBeFalsy();
const output = JSON.parse(getFirstText(result));
expect(output.tiles.map((t: { id: string }) => t.id)).toEqual([
'markdown-tile',
]);
});

it('keeps PromQL tiles when clickstack_save_dashboard updates the dashboard', async () => {
const dashboard = await createDashboard();

const result = await callTool(ctx.client!, 'clickstack_save_dashboard', {
id: dashboard._id.toString(),
name: 'PromQL dashboard',
tiles: [
{
id: 'markdown-tile',
name: 'Updated notes',
config: { displayType: 'markdown', markdown: 'Updated' },
},
],
});

expect(result.isError).toBeFalsy();
const stored = await Dashboard.findById(dashboard._id).lean();
expect(stored?.tiles.map(t => t.id)).toEqual([
'markdown-tile',
'promql-tile',

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — No test for a request tile that reuses a hidden PromQL tile's id

The new merge in saveDashboard.ts:329-336 has a second branch: a request tile whose id matches a hidden PromQL tile replaces it instead of being added next to it. The PR description promises this, but no test sends a tile with id promql-tile. If the !requestTileIds.has(tile.id) filter breaks, the stored dashboard ends up with two tiles sharing one id. Add a case that saves { id: 'promql-tile', ... } and asserts exactly one promql-tile with the new config.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Comment thread
karl-power marked this conversation as resolved.
Resolved
]);
expect(stored?.tiles[1].config).toEqual(promqlTile.config);
});
});
14 changes: 13 additions & 1 deletion packages/api/src/mcp/tools/dashboards/saveDashboard.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { isPromqlSavedChartConfig } from '@hyperdx/common-utils/dist/guards';
import type { DashboardContainer } from '@hyperdx/common-utils/dist/types';
import { uniq } from 'lodash';
import mongoose from 'mongoose';
Expand Down Expand Up @@ -318,10 +319,21 @@ async function updateDashboard({
(existingDashboard.filters ?? []).map((f: { id: string }) => f.id),
);

const internalTiles = convertExternalTilesToInternal(
const requestTiles = convertExternalTilesToInternal(
tilesWithId,
existingTileIds,
);
// MCP reads hide PromQL tiles, so the agent's tile list never contains them.
// Keep them rather than delete tiles it could not see. A request tile that
// reuses a hidden tile's id replaces it. Remove with HDX-5302.
const requestTileIds = new Set(requestTiles.map(tile => tile.id));
const internalTiles = [
Comment thread
karl-power marked this conversation as resolved.
Resolved
...requestTiles,
...(existingDashboard.tiles ?? []).filter(
tile =>
isPromqlSavedChartConfig(tile.config) && !requestTileIds.has(tile.id),
),
Comment thread
karl-power marked this conversation as resolved.
Resolved
];

// Typed as `Partial<IDashboard>` (the canonical Mongo doc shape) so
// misnamed or wrong-shape fields fail at compile time, mirroring the
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7138,6 +7138,152 @@ describe('External API v2 Dashboards - new format', () => {
});
});

describe('PromQL tiles', () => {
const promqlTile = (config: Record<string, unknown> = {}) => ({
name: 'PromQL',
x: 0,
y: 0,
w: 6,
h: 3,
config: {
configType: 'promql',
displayType: 'line',
sourceId: promqlSource._id.toString(),
expressions: [{ expression: 'up', alias: 'Up' }],
legendTemplate: '{{job}}',
...config,
},
});

const postTile = (config: Record<string, unknown> = {}) =>
authRequest('post', BASE_URL).send({
name: 'PromQL dashboard',
tiles: [promqlTile(config)],
tags: [],
});

it('round-trips a PromQL tile through POST and GET', async () => {
const create = await postTile().expect(200);
const expected = { ...promqlTile().config, fillNulls: true };
expect(create.body.data.tiles[0].config).toEqual(expected);

const get = await authRequest(
'get',
`${BASE_URL}/${create.body.data.id}`,
).expect(200);
expect(get.body.data.tiles[0].config).toEqual(expected);
});

it('keeps PromQL tiles when a dashboard is read and saved back', async () => {
const promqlConfig = {
configType: 'promql',
name: 'Saved in the app',
displayType: DisplayType.Number,
source: promqlSource._id.toString(),
promqlExpression: [{ expression: 'up', reducer: 'max' }],
};
const dashboard = await createTestDashboard({
tiles: [
{ id: 'promql-tile', x: 0, y: 0, w: 6, h: 3, config: promqlConfig },
{
id: 'markdown-tile',
x: 6,
y: 0,
w: 6,
h: 3,
config: {
name: 'Notes',
displayType: DisplayType.Markdown,
markdown: 'Notes',
source: '',
where: '',
select: [],
},
},
],
});

const get = await authRequest(
'get',
`${BASE_URL}/${dashboard._id}`,
).expect(200);
const { name, tiles, tags } = get.body.data;
await authRequest('put', `${BASE_URL}/${dashboard._id}`)
.send({ name, tiles, tags })
.expect(200);

const stored = await Dashboard.findById(dashboard._id).lean();
expect(stored?.tiles.find(t => t.id === 'promql-tile')?.config).toEqual(
promqlConfig,
);
});

it('rejects a PromQL tile whose source is not a PromQL source', async () => {
const res = await postTile({
sourceId: traceSource._id.toString(),
}).expect(400);
expect(JSON.stringify(res.body)).toContain(
`PromQL tiles require a PromQL source. The following source IDs are not PromQL sources: ${traceSource._id.toString()}`,
);
});

describe('when the source kind changes after the tile is saved', () => {
const createAndRetypeSource = async () => {
const create = await postTile().expect(200);
await Source.updateOne(
{ _id: promqlSource._id },
{ $set: { kind: SourceKind.Log } },
);
Comment thread
karl-power marked this conversation as resolved.
Resolved
return create.body.data;
};

it('still lets unrelated edits through', async () => {
const { id, tiles, tags } = await createAndRetypeSource();

await authRequest('put', `${BASE_URL}/${id}`)
.send({ name: 'Renamed', tiles, tags })
.expect(200);
});

it('rejects pointing the tile at a non-PromQL source', async () => {
const { id, tiles, tags } = await createAndRetypeSource();
const [tile] = tiles;

const res = await authRequest('put', `${BASE_URL}/${id}`)
.send({
name: 'Renamed',
tiles: [
{
...tile,
config: {
...tile.config,
sourceId: traceSource._id.toString(),
},
},
],
tags,
})
.expect(400);
expect(JSON.stringify(res.body)).toContain(
'PromQL tiles require a PromQL source',
);
});
});

// The builder heatmap check requires a Trace source; it must not apply.
it('accepts a PromQL heatmap on a PromQL source', async () => {
const create = await postTile({
displayType: 'heatmap',
heatmapMode: 'histogram',
expressions: [{ expression: 'sum by (le) (rate(x_bucket[5m]))' }],
}).expect(200);
expect(create.body.data.tiles[0].config).toMatchObject({
displayType: 'heatmap',
heatmapMode: 'histogram',
});
});
});

describe('Chart formulas', () => {
// Two metric operand series (A, B) — the shape the formula grammar
// references by position. Payloads go through `.send()` (untyped) so
Expand Down
50 changes: 44 additions & 6 deletions packages/api/src/routers/external-api/v2/utils/dashboards.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1359,19 +1359,21 @@ function getHeatmapTilesWithIncompatibleSources(

/**
* Returns an error message string if any of the referenced source IDs is not
* a valid PromQL source, or null if all of them are.
* a valid PromQL source, or null if all of them are. `subject` names what
* referenced them, e.g. "PromQL tiles".
*/
function getPromqlLabelFilterSourceError(
function getNonPromqlSourceError(
sources: SourceForValidation[],
referencedSourceIds: string[],
subject: string,
): string | null {
const sourceById = new Map(sources.map(s => [s._id.toString(), s]));
const invalid = [...new Set(referencedSourceIds)].filter(id => {
const source = sourceById.get(id);
return source === undefined || !isPromqlSource(source);
});
if (invalid.length === 0) return null;
return `PROMETHEUS_LABEL filters require a PromQL source. The following source IDs are not PromQL sources: ${invalid.join(', ')}`;
return `${subject} require a PromQL source. The following source IDs are not PromQL sources: ${invalid.join(', ')}`;
}

/**
Expand Down Expand Up @@ -1504,6 +1506,33 @@ function filterChangedHeatmapTiles(
});
}

/**
* Returns the source IDs of PromQL tiles to check against the PromQL
* source-kind gate. With `existingTiles` (update paths), a tile that was already
* a PromQL tile on the same source is skipped, mirroring
* `filterChangedHeatmapTiles`: a source whose kind changed after the tile was
* saved must not block unrelated dashboard edits.
*/
function getChangedPromqlTileSourceIds(
tiles: ExternalDashboardTileWithId[],
existingTiles: DashboardDocument['tiles'] | undefined,
): string[] {
const existingPromqlSources = new Map(
(existingTiles ?? []).flatMap(tile =>
isPromqlSavedChartConfig(tile.config)
? [[tile.id, tile.config.source]]
: [],
),
);
return tiles.flatMap(tile =>
isConfigTile(tile) &&
isPromqlExternalTileConfig(tile.config) &&
existingPromqlSources.get(tile.id) !== tile.config.sourceId
? [tile.config.sourceId]
: [],
);
}

/**
* Returns source IDs referenced by onClick search link-outs (mode=id,
* type=search) whose source kind is not log or trace. The /search destination
Expand Down Expand Up @@ -1711,7 +1740,7 @@ export type TileValidationContext = {

/**
* Run the full suite of tile validation checks (sources, connections,
* heatmap source-kind, onClick targets, container/tab refs). Returns
* heatmap and PromQL source-kind, onClick targets, container/tab refs). Returns
* `null` when all checks pass, or an error message string on failure.
*
* Consolidates the ~95-line validation block that was previously
Expand Down Expand Up @@ -1789,11 +1818,20 @@ export async function validateDashboardTiles(
return `Tiles with formulas require a Metric, Log, or Trace source. The following source IDs are not formula-capable: ${formulaIncompatibleSources.join(', ')}`;
}

// Validate that PROMETHEUS_LABEL filters reference PromQL sources
// PromQL tiles and PROMETHEUS_LABEL filters query through their source's
// connection and TimeSeries table, which only a PromQL source carries.
const promqlTileError = getNonPromqlSourceError(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — PromQL source check re-validates every PromQL tile on update, so one tile with a stale source blocks unrelated PUTs

Unlike the heatmap and formula checks just above, which only re-check new or changed tiles on update (filterChangedHeatmapTiles / filterChangedFormulaTiles), this check runs on every PromQL tile in the request. Suppose a PromQL tile's source later changes kind. A GET→PUT round trip that only renames the dashboard then returns 400, which is the case the heatmap gate's doc comment (around line 1461) was written to avoid. When existingTiles is set, limit the check to PromQL tiles that are new, were just switched to PromQL, or changed sourceId.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

sources,
getChangedPromqlTileSourceIds(tiles, existingTiles),
'PromQL tiles',
);
Comment thread
karl-power marked this conversation as resolved.
Resolved
if (promqlTileError != null) return promqlTileError;

const promqlLabelFilters = (filters ?? []).filter(isPrometheusLabelFilter);
const promqlLabelFilterError = getPromqlLabelFilterSourceError(
const promqlLabelFilterError = getNonPromqlSourceError(
sources,
promqlLabelFilters.map(f => f.sourceId),
'PROMETHEUS_LABEL filters',
);
if (promqlLabelFilterError != null) return promqlLabelFilterError;

Expand Down
Loading