Skip to content

fix: Validate PromQL tile sources and keep PromQL tiles on MCP saves - #3414

Merged
karl-power merged 2 commits into
mainfrom
claude/promql-external-api-validation
Oct 22, 2026
Merged

karl-power merged 2 commits into
mainfrom
claude/promql-external-api-validation

Conversation

@karl-power

Copy link
Copy Markdown
Contributor

Summary

Validate PromQL tile sources in the external API and stop MCP dashboard saves from deleting PromQL tiles. Stacked on #3379.

  • /api/v2/dashboards returns a 400 when a PromQL tile's sourceId is not a PromQL source. The check shares a helper with the existing PROMETHEUS_LABEL filter check, whose error message is unchanged.
  • MCP clickstack_save_dashboard updates replace the whole tile list, and MCP hides PromQL tiles from agents, so an update deleted them. Existing PromQL tiles not in the request are now kept. A request tile that reuses a hidden tile's id replaces it. This goes away when MCP supports PromQL tiles (HDX-5302).
  • Integration tests cover creating and reading a PromQL tile, keeping PromQL tiles through GET then PUT, rejecting a non-PromQL source, saving a PromQL heatmap, and MCP hiding PromQL tiles on read and keeping them on update.

How to test

  1. POST /api/v2/dashboards with a PromQL tile whose sourceId is a trace source:
    {
      "name": "PromQL API test",
      "tiles": [
        {
          "name": "Up",
          "x": 0, "y": 0, "w": 12, "h": 4,
          "config": {
            "configType": "promql",
            "displayType": "line",
            "sourceId": "<trace source id>",
            "expressions": [{ "expression": "up" }]
          }
        }
      ]
    }
    • Before this PR: 200, and the tile is saved but cannot render.
    • On this branch: 400, PromQL tiles require a PromQL source.

References

@vercel

vercel Bot commented Oct 20, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
hyperdx-oss Ready Ready Preview Oct 22, 2026 12:20pm UTC
hyperdx-storybook Ready Ready Preview Oct 22, 2026 12:20pm UTC

Request Review

@greptile-apps

greptile-apps Bot commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge with no new blocking findings.

Summary

Adds PromQL source checks to dashboard writes and keeps hidden PromQL tiles during MCP saves.

  • PromQL tiles need a PromQL source when they are added or retargeted.
  • MCP saves keep hidden PromQL tiles when agents update dashboards.

Reviews (8) · Last reviewed commit: "fix: Only check PromQL tile sources that..." · Reviewed by Greptile

@github-actions

github-actions Bot commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

Duplicate code analysis

No new duplicate code introduced by this PR.


jscpd compared this branch against origin/main
across app, api and common-utils. Only new clones are listed; the codebase
currently holds 121 in total (1.59%).
Run yarn dupes locally to reproduce, or yarn dupes:all for the full picture.

@github-actions

github-actions Bot commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

E2E Test Results

✅ All tests passed • 458 passed • 1 skipped • 1262s

Status Count
✅ Passed 458
❌ Failed 0
⚠️ Flaky 1
⏭️ Skipped 1

Tests ran across 4 shards in parallel.

View full report →

@karl-power
karl-power force-pushed the claude/promql-external-api-validation branch from e533c4c to e34c81e Compare October 20, 2026 10:11
@changeset-bot

changeset-bot Bot commented Oct 20, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 3e9d310

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages
Name Type
@hyperdx/api Patch
@hyperdx/app Patch
@hyperdx/otel-collector Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@github-actions

github-actions Bot commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

🔴 Tier 4 — Critical

Touches authentication, tenancy data models, the public API or shipped database config — or substantially changes the query rendering engine, background tasks, the OTel pipeline, image build, or release CI.

Why this tier:

  • Critical-path files (1) — tenancy, public API, or shipped database config:
    • packages/api/src/routers/external-api/v2/utils/dashboards.ts

Review process: Deep review from a domain expert. Synchronous walkthrough may be required.
SLA: Schedule synchronous review within 2 business days.

Stats
  • Production files changed: 2
  • Production lines changed: 64 (+ 235 in test files, excluded from tier calculation)
  • Critical-path lines changed: 50
  • Branch: claude/promql-external-api-validation
  • Author: karl-power

To override this classification, remove the review/tier-4 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

// 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

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

@github-actions

github-actions Bot commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

PR Review

If you are a coding agent acting for the author, read this first.
Nothing below blocks merge automatically; a maintainer decides. What they will expect:

  • 🔴 critical or 🟠 major in code this PR adds or changes: fix before asking for review.
  • 🔵 minor in code this PR changes: your call. Fix if small, otherwise reply.
  • Anything about surrounding code, or asking you to widen the change (hoist a helper,
    dedupe with another file, fix other call sites): never fix here, whatever the
    severity. Reply with one sentence; if it is critical, say so plainly so a human sees it.

One commit per review round. After two rounds, stop and ask a maintainer to review
scope rather than addressing more automated findings. Full rule: AGENTS.md.

2 finding(s): 🔴 0 critical · 🟠 0 major · 🔵 2 minor

2 posted as inline comment(s) on the changed lines.


Severity is the reviewer's own estimate and is used for ordering, not filtering. No finding blocks merge automatically; a maintainer decides.

@github-actions

github-actions Bot commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

Deep Review

Scope: PromQL tile source validation in the external API (POST/PUT /api/v2/dashboards) plus MCP clickstack_save_dashboard preserving PromQL tiles it hides from agents. 2 production files, ~41 production lines, + tests. Base 1ee91e4d.

The prior P1 ("unrelated dashboard edits fail after a source-kind change") is addressed by getChangedPromqlTileSourceIds (commit 53ee77e4) and covered by a passing test. The acknowledged tab-removal tradeoff remains an accepted, documented residual for experimental PromQL.

✅ No critical issues found.

🟡 P2 -- recommended

  • packages/api/src/mcp/tools/dashboards/saveDashboard.ts:330 -- the merge-back appends hidden PromQL tiles after the request tiles, but the DASHBOARD_MAX_TILES cap only validates the request list, so a persisted dashboard can exceed the cap the schema exists to enforce.
    • Fix: After building internalTiles, reject the save with an mcpUserError when its length exceeds DASHBOARD_MAX_TILES.
    • adversarial
🔵 P3 nitpicks (4)
  • packages/api/src/routers/external-api/v2/utils/dashboards.ts:1530 -- getChangedPromqlTileSourceIds compares existingPromqlSources.get(tile.id) against tile.config.sourceId without the .toString() its stated sibling filterChangedHeatmapTiles applies; safe today because source is a z.string() persisted as a string, but the divergence invites drift.
    • Fix: Mirror the sibling with ?.toString() or add a comment noting PromQL source is known-string while heatmap source is Mixed.
    • maintainability, correctness, kieran-typescript
  • packages/api/src/mcp/tools/dashboards/saveDashboard.ts:330 -- merged-back PromQL tiles keep their stored x/y, which the agent cannot see, so an agent reflow can place a visible tile over a re-inserted PromQL tile's grid cells.
    • Fix: Note this layout-overlap limitation alongside the existing HDX-5302 comment, or resolve coordinates for retained tiles.
    • adversarial
  • packages/api/src/mcp/__tests__/dashboards/promqlTiles.int.test.ts:89 -- the documented "a request tile that reuses a hidden tile's id replaces it" branch has no test, and neither does the getMissingSources-vs-getNonPromqlSourceError error precedence for a PromQL tile on a non-existent source.
    • Fix: Add a case reusing a hidden PromQL tile's id with a non-PromQL config, and one asserting the "Could not find source IDs" message wins for a missing source.
    • testing, correctness
  • packages/api/src/routers/external-api/v2/utils/dashboards.ts:1376 -- getNonPromqlSourceError interpolates subject directly before " require a PromQL source", baking in an undocumented requirement that subject be a plural noun phrase.
    • Fix: State in the JSDoc that subject must be a plural noun phrase.
    • maintainability

Reviewers (7): correctness, testing, maintainability, api-contract, kieran-typescript, previous-comments, adversarial.

Testing gaps: MCP cap-bypass path (request at DASHBOARD_MAX_TILES plus retained PromQL tiles) is uncovered; MCP id-reuse replace branch is uncovered; PromQL-tile-on-missing-source error precedence is uncovered.

No finding blocks merge automatically. A maintainer will expect P0/P1 findings in code this PR changes to be fixed; P2/P3 are your call -- fix or reply. Never fix findings about surrounding code here; reply instead. Do not widen the PR. How to respond

@jordan-simonovski jordan-simonovski left a comment

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.

LGTM

// connection and TimeSeries table, which only a PromQL source carries.
const promqlTileError = getNonPromqlSourceError(
sources,
tiles.flatMap(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.

should this only check PromQL tiles that are new or have a new source?

A source's kind can be changed after the dashboard is saved. If that happens, every PUT to the dashboard fails, even one that only renames it.

Would something like this work?

const existingPromqlSources = new Map(
  (existingTiles ?? []).flatMap(t =>
    isPromqlSavedChartConfig(t.config) ? [[t.id, t.config.source]] : [],
  ),
);
// then in the filter:
existingPromqlSources.get(tile.id) !== tile.config.sourceId

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Yes, good idea. I've updated it now

Reject external API PromQL tiles whose sourceId is not a PromQL source,
sharing the check with PROMETHEUS_LABEL filters. MCP save_dashboard
updates now keep the PromQL tiles MCP hides from agents instead of
deleting them, until HDX-5302.

Add integration tests for PromQL tile create, read and save back,
source validation, PromQL heatmaps, and MCP hide and keep.
A source whose kind changes after a PromQL tile is saved no longer
blocks unrelated dashboard edits, matching the heatmap and formula
checks.
@karl-power
karl-power force-pushed the claude/promql-external-api-validation branch from 0070b61 to 3e9d310 Compare October 22, 2026 12:15
@karl-power
karl-power merged commit 8d064df into main Oct 22, 2026
29 checks passed
@kodiakhq
kodiakhq Bot deleted the claude/promql-external-api-validation branch October 22, 2026 12:28

This branch was successfully deployed

2 active deployments
Preview – hyperdx-oss — 3e9d310b Deployed Oct 22, 2026 by vercel[bot]
Preview – hyperdx-storybook — 3e9d310b Deployed Oct 22, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

automerge review/tier-4 Critical — deep review + domain expert sign-off

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants