Skip to content

feat: Support PromQL dashboard tiles in the external API - #3379

Merged
karl-power merged 2 commits into
mainfrom
promql-external-api
Oct 21, 2026
Merged

karl-power merged 2 commits into
mainfrom
promql-external-api

Conversation

@karl-power

Copy link
Copy Markdown
Contributor

Summary

Add PromQL dashboard tiles to the external API (/api/v2/dashboards), so they can be read, created, and saved back without being lost.

  • GET now returns PromQL tiles. Previously they were left out, so saving a dashboard back through the API deleted them.
  • POST and PUT accept PromQL tiles as configType: "promql" with a sourceId, a list of expressions (expression, alias, and queryType/reducer where the display type supports them), granularity, legendTemplate, heatmap settings, and the display options the chart editor saves for each display type.
  • expressions is always a list in the API. The saved tile config allows promqlExpression to be either a list or a single expression string (the format before multi-expression support), so a stored string such as "up" is returned as [{ "expression": "up" }].
  • PromQL tiles have no connectionId, unlike raw SQL tiles. The connection is read from the PromQL source at query time, so it is never returned or saved on the tile.
  • The heatmap and formula checks in validateDashboardTiles now apply only to builder tiles, so a PromQL heatmap is not rejected for not using a Trace source.
  • Inline alert configs still reject configType: "promql".
  • MCP dashboard tools keep hiding PromQL tiles until MCP can edit them (HDX-5302).

How to test

Read and save back

  1. In the app, create a dashboard with one PromQL tile (e.g. expression up) and one other tile.
  2. GET /api/v2/dashboards/<id>.
    • On main: the PromQL tile is missing from tiles.
    • On this branch: the PromQL tile is returned with configType: "promql".
  3. PUT /api/v2/dashboards/<id> with the data object from that response.
    • On main: the PromQL tile is deleted from the dashboard.
    • On this branch: the PromQL tile is still on the dashboard and renders as before.

Create

  1. POST /api/v2/dashboards with:
    {
      "name": "PromQL API test",
      "tiles": [
        {
          "name": "Up",
          "x": 0, "y": 0, "w": 12, "h": 4,
          "config": {
            "configType": "promql",
            "displayType": "line",
            "sourceId": "<promql source id>",
            "expressions": [{ "expression": "up", "alias": "Up" }],
            "legendTemplate": "{{job}}"
          }
        }
      ]
    }
    • On main: 400, configType must be "sql" or omitted.
    • On this branch: 200, and the response contains the tile as sent.
  2. On this branch, open the new dashboard in the app: the tile renders the up series. Edit the tile and confirm the expression, alias, and legend template are filled in.

References

@vercel

vercel Bot commented Oct 15, 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 21, 2026 7:02am UTC
hyperdx-storybook Ready Ready Preview Oct 21, 2026 7:02am UTC

Request Review

@changeset-bot

changeset-bot Bot commented Oct 15, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 1ee91e4

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 Minor
@hyperdx/app Minor
@hyperdx/otel-collector Minor

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 15, 2026 •

Copy link
Copy Markdown
Contributor

Duplicate code analysis

3 new clones introduced by this PR.

  • packages/api/src/mcp/tools/dashboards/getDashboardTile.ts:43-57 ↔ packages/api/src/mcp/tools/dashboards/queryTile.ts:70-84 — 15 lines
  • packages/api/src/mcp/tools/dashboards/queryTile.ts:63-81 ↔ packages/api/src/mcp/tools/dashboards/queryTiles.ts:212-230 — 19 lines
  • packages/api/src/routers/external-api/v2/utils/dashboards.ts:1421-1431 ↔ packages/api/src/routers/external-api/v2/utils/dashboards.ts:1469-1479 — 11 lines

If one of these duplicates a helper that already exists, import it instead
of redefining it. If the duplication is deliberate, ignore this comment —
the check is advisory and never fails the build.


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

@greptile-apps

greptile-apps Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge with the verified stack follow-ups; the long-expression save issue is non-blocking.

Fix All in Claude CodeFindings

  1. P2 Long queries block saves ▶

Summary

Adds PromQL tiles to external dashboard reads and writes, including legacy string expressions and display-specific settings.

  • Dashboard API reads and writes keep PromQL tiles intact.
  • Changing a dashboard tile to PromQL removes its attached alert.

Reviews (6) · Last reviewed commit: "fix: Keep PromQL tile description and li..." · Reviewed by Greptile

Comment thread packages/api/src/utils/zod.ts Resolved
@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

E2E Test Results

✅ All tests passed • 446 passed • 1 skipped • 1626s

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

Tests ran across 4 shards in parallel.

View full report →

@github-actions

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: 8
  • Production lines changed: 437 (+ 301 in test files, excluded from tier calculation)
  • Critical-path lines changed: 236
  • Branch: promql-external-api
  • 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.

w: 6,
h: 3,
config: {
configType: 'promql',

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 integration test covers the REST create, read and save-back path for PromQL tiles or their validation

The only new integration test with a PromQL tile checks alert cleanup. Nothing exercises the main path in the PR description: a PromQL tile surviving GET → PUT, POST with a PromQL heatmap no longer being rejected by the heatmap gate, or a missing or wrong PromQL sourceId being rejected. The unit tests call the converters directly and skip validateDashboardTiles. Fix: add integration tests for a PromQL heatmap POST (expect 200), a GET → PUT round-trip that keeps the tile, and a POST whose sourceId points to a non-PromQL source (expect 400 once the source-kind check is added).

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

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.

4 finding(s): 🔴 0 critical · 🟠 3 major · 🔵 1 minor

1 posted as inline comment(s) on the changed lines. 3 listed below.

Findings outside the changed lines

  • 🟠 packages/api/src/routers/external-api/v2/utils/dashboards.ts:1792 — PromQL tile sourceId is only checked for existence, not that the source is a PromQL source → getMissingSources only checks that the ID exists, and this PR removes PromQL tiles from the heatmap/formula source gates. As a result, POST /api/v2/dashboards with configType: "promql" and the sourceId of a log, trace or metric source returns 200. The tile is saved, and at render time it sends PromQL to a source that isn't Prometheus, so the query fails. The editor never allows this (getAllowedSourceKinds in packages/app/src/components/ChartEditor/utils.ts returns only SourceKind.Promql). Fix: collect the sourceId of every PromQL tile and pass them through the existing getPromqlLabelFilterSourceError / isPromqlSource check (same file, around line 1364), or a variant of it with a tile-specific message, inside validateDashboardTiles.
  • 🟠 packages/api/src/routers/external-api/v2/dashboards.ts:1517 — OpenAPI spec not updated for the new configType: "promql" tile variant → The JSDoc schemas (LineChartConfig, BarChartConfig, StackedLineChartConfig, and the table/number/pie/bar/heatmap configs) still describe only builder and sql variants, and the discriminator mapping lists only sql. packages/api/openapi.json was not regenerated either. GET now returns PromQL tiles that match no documented schema, so generated clients and the Terraform provider will reject or strip them. Fix: add *PromqlChartConfig schemas (sourceId, expressions[], granularity, legendTemplate, heatmapMode and so on), add promql to each discriminator mapping, and regenerate openapi.json.
  • 🟠 packages/api/src/mcp/tools/dashboards/saveDashboard.ts:321 — MCP save_dashboard update deletes PromQL tiles that hidePromqlTiles hid from the agent → get_dashboard hides PromQL tiles, so an agent sends back only the tiles it can see. updateDashboard then replaces tiles with that list, deletes the PromQL tiles, and cleanupDashboardAlerts treats them as removed. The REST API no longer loses these tiles, but the MCP path still does, and the new explicit hidePromqlTiles flag hides that from the agent. Fix: in updateDashboard, add the existing PromQL tiles from existingDashboard.tiles that the request does not mention back onto internalTiles before the $set. Do the same in existingTileIds so they are not counted as removed.

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

@github-actions

Copy link
Copy Markdown
Contributor

Deep Review

✅ No critical issues found. This is an additive, well-tested feature with disciplined type-level handling; the two previously-flagged P1 regressions (alerts left on tiles switched to PromQL, and lineInterpolation being dropped) are confirmed fixed in the current diff. The items below are recommendations and nits, plus one pre-existing data-loss path worth a heads-up.

🟡 P2 -- recommended

  • packages/api/src/routers/external-api/v2/utils/dashboards.ts:1745 -- validateDashboardTiles only checks that a PromQL tile's sourceId exists, not that the source is a PromQL source, so POST/PUT persists a configType:"promql" tile on a Log/Trace/Metric source that can never render (the query path later returns 404).
    • Fix: Add a PromQL tile source-kind gate mirroring the existing PROMETHEUS_LABEL filter check, or ensure the separate source-kind validation lands no later than this change.
    • adversarial, previous-comments, testing
  • packages/api/src/routers/external-api/v2/dashboards.ts:1762 -- the hand-written OpenAPI TileConfig schema still enumerates only builder and SQL variants, so GET now returns and POST/PUT now accept configType:"promql" tiles that the published contract does not describe, and a strict codegen client routing a PromQL tile to LineChartConfig would reject it.
    • Fix: Add PromQL chart-config variants (per display type, with sourceId/expressions and no connectionId) to the documented request/response schemas, or land the documentation alongside this change.
    • api-contract, previous-comments
  • packages/api/src/routers/external-api/__tests__/dashboards.int.test.ts:5605 -- the only integration test sending a PromQL tile asserts solely that an alert is deleted; no test POSTs/PUTs a PromQL tile and then GETs it to confirm the config persists and reads back intact.
    • Fix: Add an integration test that saves a PromQL tile over HTTP, re-reads it, and asserts the returned config matches.
    • testing, project-standards
  • packages/api/src/routers/external-api/v2/utils/__tests__/dashboards.test.ts:741 -- the round-trip it.each covers line/stacked_line/stacked_bar/table/number/pie/heatmap but omits categorical bar, which is a distinct ternary branch in both converters and its own schema member.
    • Fix: Add a bar case to the round-trip it.each.
    • testing
  • packages/api/src/mcp/tools/dashboards/getDashboard.ts:43 -- six MCP tools were changed to pass { hidePromqlTiles: true }, but only the underlying converter is unit-tested with the flag; no test asserts these tools actually omit PromQL tiles from their responses.
    • Fix: Add at least one MCP tool test asserting a PromQL tile is absent from the tool output.
    • testing
🔵 P3 nitpicks (5)
  • packages/api/src/routers/external-api/v2/utils/dashboards.ts:917 -- convertExternalPromqlConfigToInternal's switch has no default: config satisfies never, unlike every sibling converter in the file; it is currently safe only because the non-undefined return type makes TS flag a missing arm.
    • Fix: Add a default: config satisfies never for consistency and future-proofing.
  • packages/api/src/utils/zod.ts:1333 -- externalPromqlStackedChartConfigSchema hardcodes displayType: 'stacked_bar' but is reused as the base for the line and stacked_line members, so its name misdescribes its role as the shared time-series base.
    • Fix: Rename it to a time-series/time-chart base name.
  • packages/api/src/mcp/tools/dashboards/getDashboard.ts:42 -- the identical convertToExternalDashboard(dashboard, { hidePromqlTiles: true }) call is duplicated across six MCP tools for an explicitly temporary workaround.
    • Fix: Wrap it in one MCP-local helper so the flag lives in a single place and later removal touches one file.
  • packages/api/src/utils/zod.ts:806 -- the configType error message is now parameterized per surface; any external consumer or published snippet asserting the old literal string would break.
    • Fix: Confirm no SDK or docs quote the previous error string.
  • packages/api/src/routers/external-api/v2/utils/dashboards.ts:841 -- the Search/Markdown/EventPatterns → line fallback branch (a logged, lossy downgrade) and the pie/bar limit three-state (0/omitted) are not exercised by any test.
    • Fix: Add coverage for the unsupported-display-type fallback and the limit three-state serialization.

⚪ Pre-existing (not introduced by this diff)

  • packages/api/src/mcp/tools/dashboards/saveDashboard.ts:331 -- a full MCP updateDashboard rebuilds the tiles array only from tiles the agent submitted and $set-replaces the whole array; because MCP reads hide PromQL tiles, a full save silently deletes them. This is the same round-trip data loss the PR fixes for the REST API, and it existed before this change (PromQL tiles were already dropped from all MCP reads), so this diff neither introduces nor worsens it. patchDashboard is unaffected (it splices a single tile into the persisted array).
    • Fix: When MCP write support arrives, merge persisted PromQL tiles back before $set, or reject a full save when hidden tiles exist; until then, call out the write-path risk alongside the read-side deferral.
    • adversarial, agent-native

Reviewers (10): correctness (did not return in window), adversarial, testing, maintainability, project-standards, api-contract, kieran-typescript, previous-comments, agent-native, learnings-researcher. No applicable past learnings were found in docs/solutions/.

Coverage note: The correctness reviewer did not complete within the review window; its logic/edge-case scope overlaps substantially with the completed adversarial and kieran-typescript reviewers, which verified converter exhaustiveness (all 8 display types handled; no implicit undefined return) and found the type guards and discriminated-union routing sound.

Testing gaps:

  • No integration test proves a PromQL tile survives a create/save → GET HTTP round-trip (only the alert-deletion side effect is asserted).
  • Categorical bar round-trip, the Search/Markdown/EventPatterns → line fallback, and the pie/bar limit three-state are uncovered.
  • No MCP tool-level test verifies the hidePromqlTiles behavior across the six changed tools.

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

… alerts

Round-trip the tile description and lineInterpolation on PromQL tiles so
saving a dashboard back through the external API does not reset them.
Delete a tile's alert when it is switched to PromQL, since PromQL tiles
cannot be alerted on.
Comment on lines +659 to +660
expression: z.string().max(10000),
alias: z.string().max(10000).optional(),

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.

P2 Long queries block saves

The new 10,000-character caps reject valid saved PromQL expressions. PromqlSeriesSchema and the chart editor allow longer expressions, and GET returns them unchanged. Saving that response through PUT then fails with 400, even if the caller changed only the dashboard name.

Keep the accepted length consistent with saved tiles, or preserve existing expressions that exceed the new limit. Add a round-trip test with a long label matcher.

Fix in Claude Code Fix in Conductor Fix in Cursor Fix in Codex

@karl-power
karl-power merged commit 9c2c703 into main Oct 21, 2026
32 of 55 checks passed
@kodiakhq
kodiakhq Bot deleted the promql-external-api branch October 21, 2026 08:45

This branch was successfully deployed

2 active deployments
Preview – hyperdx-oss — 1ee91e4d Deployed Oct 21, 2026 by vercel[bot]
Preview – hyperdx-storybook — 1ee91e4d Deployed Oct 21, 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.

2 participants