Skip to content

fix: resolve PromQL queries through their source - #3372

Merged
kodiakhq[bot] merged 4 commits into
mainfrom
agent/backport-promql-source-refactor
Oct 14, 2026
Merged

kodiakhq[bot] merged 4 commits into
mainfrom
agent/backport-promql-source-refactor

Conversation

@karl-power

@karl-power karl-power commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Summary

PromQL API requests now name a PromQL source (sourceId) instead of a connection and table; the server reads both from the source.

  • /api/v1/prometheus/* routes take sourceId instead of connectionId (400 if missing; 404 if the source doesn't exist, isn't PromQL, or its connection is gone)
  • Caller-supplied database/table are ignored for ClickHouse and not forwarded to external Prometheus endpoints
  • Saved PromQL chart configs require source and no longer persist connection, which is filled from the source at query time. Existing tiles with a stored connection still load
  • The app sends sourceId from charts, autocomplete, and PromQL label dashboard filters
  • MCP runSavedChartConfig rejects PromQL tiles explicitly
  • Breaking: direct API callers must send sourceId, and provisioned dashboard PromQL tiles must set source

Context

Backport of an already-reviewed enterprise change that adds source RBAC to the PromQL API, minus the RBAC parts (route role checks, source access rules, and their tests). Also omitted: the enterprise PromQL feature-check middleware (here the router is only mounted when ENABLE_PROMQL=true) and an MCP notebook fix (no notebooks here).

How to test on Vercel preview

  • Create a PromQL tile and ensure it works, saves, and reloads.

References

Related PRs: https://github.com/DeploySentinel/hyperdx-ee/pull/3614

Backport of the non-RBAC part of the EE change that moved the PromQL API from connectionId to sourceId. The connection and TimeSeries table now always come from the PromQL source; caller-supplied database/table are ignored for ClickHouse and not forwarded to external Prometheus. Saved PromQL chart configs require source and no longer persist connection.
@changeset-bot

changeset-bot Bot commented Oct 14, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: d1ff56a

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

This PR includes changesets to release 4 packages
Name Type
@hyperdx/common-utils Patch
@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

@vercel

vercel Bot commented Oct 14, 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 14, 2026 4:49pm UTC
hyperdx-storybook Ready Ready Preview Oct 14, 2026 4:49pm UTC

Request Review

@github-actions github-actions Bot added the review/tier-3 Standard — full human review required label Oct 14, 2026
@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

🟡 Tier 3 — Standard

Introduces new logic, modifies core functionality, or touches areas with non-trivial risk.

Why this tier:

  • Diff size: 356 production lines changed (Tier 2 max: < 250)
  • Cross-layer change: touches frontend (packages/app) + backend (packages/api) + shared utils (packages/common-utils)
  • Touches API routes or data models — hidden complexity risk

Review process: Full human review — logic, architecture, edge cases.
SLA: First-pass feedback within 1 business day.

Stats
  • Production files changed: 11
  • Production lines changed: 356 (+ 1024 in test files, excluded from tier calculation)
  • Branch: agent/backport-promql-source-refactor
  • Author: karl-power

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

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Duplicate code analysis

3 new clones introduced by this PR.

  • packages/api/src/routers/api/prometheus.ts:576-610 ↔ packages/api/src/routers/api/prometheus.ts:686-716 — 35 lines
  • packages/api/src/routers/api/prometheus.ts:576-592 ↔ packages/api/src/routers/api/prometheus.ts:812-830 — 17 lines
  • packages/api/src/routers/api/prometheus.ts:591-610 ↔ packages/api/src/routers/api/prometheus.ts:1018-1034 — 20 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 124 in total (1.71%).
Run yarn dupes locally to reproduce, or yarn dupes:all for the full picture.

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

E2E Test Results

✅ All tests passed • 413 passed • 1 skipped • 1454s

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

Tests ran across 4 shards in parallel.

View full report →

@greptile-apps

greptile-apps Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 5/5

[High impact] The PR appears safe to merge with the documented requirement that direct callers and provisioned PromQL tiles supply a source.

Summary

PromQL requests now name a source. The server reads its connection and table instead of trusting caller-supplied targets.

  • PromQL API requests resolve their connection and table through a source ID.
  • Saved PromQL charts keep their source and fill in connection details when queried.
  • The app sends a source ID for PromQL charts and metadata lookups.
  • MCP gives a clear response when a saved chart uses PromQL.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Chart or label lookup] -->|sourceId| B[PromQL API]
  B --> C[Find team-owned PromQL source]
  C --> D[Find source connection]
  D --> E{Backend}
  E -->|ClickHouse| F[Query source database and table]
  E -->|Prometheus| G[Forward without caller database or table]
Loading

Reviews (4) · Last reviewed commit: "Merge branch 'main' into agent/backport-..." · Reviewed by Greptile

Comment thread packages/common-utils/src/types.ts Resolved
@github-actions

github-actions Bot commented Oct 14, 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.

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

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

Findings outside the changed lines

1 minor
  • 🔵 packages/app/src/components/DBEditTimeChartForm/utils.ts:70 — isQueryReady still gates PromQL on connection, not on the sourceId the request now depends on → Requests now send only config.source, but readiness is still checked against queriedConfig.connection. convertFormStateToChartConfig sets source: source?.id ?? form.source ?? '' (packages/app/src/components/ChartEditor/utils.ts:383), so when the form still holds a non-PromQL source, the leftover log-source id is sent and the preview shows a 404 'Source not found' error instead of staying not-ready. A form connection with no source sends sourceId='' and gets a 400. Fix: check queriedConfig.source here, and pass a source only when the resolved source is a PromQL source.

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

Copy link
Copy Markdown
Contributor

Deep Review

Scope: PromQL API reroutes queries through a sourceId (server resolves connection + TimeSeries table from the source); source becomes required and connection drops from the persisted PromQL chart config. Diff base 2c2295fd. 11 production files, broad test updates.

Intent: Backport of a reviewed enterprise change, minus the source-RBAC layer. Callers name a PromQL source; the server reads connection and table from it so a request can only reach data through a source.

✅ No critical (P0/P1) issues found. Security scoping is intact — resolvePromqlTarget team-scopes both getSource and getConnectionById, source-derived database/table are spread last so a caller cannot override them, and proxyToPrometheus's own param allowlist drops sourceId/injected keys before forwarding to external Prometheus or the ClickHouse prometheus_api_v1 endpoint. The two prior review findings (cache invalidation on source update, the removed banner comment) are genuinely resolved in the current head.

🟡 P2 — recommended

  • packages/common-utils/src/types.ts:1917 — Making persisted source required (z.string().min(1)) while the full dashboard body is re-validated on save (DashboardWithoutIdSchema in dashboards.ts POST/PATCH) means any already-persisted PromQL tile lacking source would make its entire dashboard fail to save, and no test exercises the "existing tiles still load/save" compatibility claim.
    • Fix: Add an integration test that loads and re-saves a dashboard whose PromQL tile carries only connection (no source), and confirm the intended behavior for that legacy shape.
    • orchestrator, learnings-researcher
  • packages/app/src/source.ts:209 — The three PromQL cache keys in PROMQL_SOURCE_QUERY_KEYS are bare string literals duplicated from usePromqlMetadata.ts and usePromqlLabelFilterValues.tsx, and the unit test re-hardcodes the same literals, so renaming a key in a hook silently breaks invalidation while leaving both hook and test green.
    • Fix: Export each query-key prefix as a named constant from its defining hook and build both the useQuery keys and PROMQL_SOURCE_QUERY_KEYS (and the test) from those constants.
    • maintainability, kieran-typescript
  • packages/common-utils/src/types.ts:1930 — Runtime connection (and sibling from) remain required on PromqlChartConfigSchema but are no longer read on the PromQL query path (promqlChartQuery.ts now sends only sourceId), leaving a required field that every constructor must populate with a ?? '' placeholder yet nothing consumes.
    • Fix: Drop connection/from from PromqlChartConfigSchema and their assignments in convertFormStateToChartConfig, after confirming no alert-eval or external-API consumer still reads them.
    • maintainability, kieran-typescript
  • .changeset/promql-source-id.md:2 — A change the changeset body itself describes as breaking (routes require sourceId, persisted config requires source, provisioned PromQL tiles must set source) is bumped patch, whereas repo precedent labels breaking schema tightenings minor (packages/api/CHANGELOG.md "Breaking (minor):").
    • Fix: Raise the three bumps to minor and mark the entry as breaking per the existing CHANGELOG convention.
    • project-standards
🔵 P3 nitpicks (5)
  • packages/app/src/components/ChartEditor/utils.ts:281 — source: source?.id ?? form.source ?? '' can emit an empty-string source that the new .min(1) schema rejects on save/import; it is currently caught by form validation and by the schema, so it fails safe rather than corrupting data.
    • Fix: Return undefined (or surface a form error) instead of '' when no source resolves, so the invalid state cannot be constructed.
  • packages/api/src/routers/api/prometheus.ts:184 — prometheusEndpointParams's Omit<T,'database'|'table'> return type is a no-op against the Record<string,string> index signature it is called with, so the key exclusion exists only at runtime via lodash omit.
    • Fix: Narrow getParams' return type away from a bare index signature, or treat the function as a documented runtime-only guard.
  • packages/api/src/routers/api/prometheus.ts:595 — 'error' in target is sound today but silently inverts if a success field named error is ever added to PromqlTarget.
    • Fix: Use a named discriminant ({ ok: false, status, error } | { ok: true, ... }) across the four call sites.
  • packages/api/src/routers/api/prometheus.ts:595 — After the resolvePromqlTarget extraction, the error-response block and the Prometheus-vs-ClickHouse dispatch remain duplicated across the query/query_range/exemplars/label handlers (jscpd flagged 3 clones).
    • Fix: Add a small sendPromError(res, status, error) helper to collapse the repeated error-response block without hiding control flow.
  • packages/common-utils/src/types.ts:1914 — The persisted (PromqlBaseChartConfigSchema) vs runtime (PromqlChartConfigSchema) split has no guardrail, so a future persisted field added to the runtime schema is silently dropped on save.
    • Fix: Add a doc comment on PromqlBaseChartConfigSchema stating persisted fields belong there and runtime-only fields belong on PromqlChartConfigSchema.

Agent-native note: packages/api/src/mcp/tools/query/helpers.ts now rejects PromQL saved tiles via MCP ("PromQL tiles cannot be queried through MCP yet.") while the app can query them — a deliberate, clearly-messaged parity gap. Consider adding a tracking reference (issue/ticket) to the "yet" so the follow-up is discoverable.


Reviewers (6): security, previous-comments, project-standards, kieran-typescript, maintainability, learnings-researcher (plus orchestrator verification of the backward-compat save path, cross-team scoping, and the result discriminator).

Testing gaps:

  • No negative test that a sourceId from another team returns 404 (cross-team isolation).
  • No test asserting caller database/table are stripped from the external-Prometheus proxy while the ClickHouse prometheus_api_v1 path receives them from the source.
  • No test covering the legacy PromQL tile (stored connection, no source) load/save path that the PR claims stays compatible.
  • No test for convertFormStateToSavedChartConfig/convertFormStateToChartConfig when no source resolves (the source: '' path).

Coverage note: The correctness, adversarial, api-contract, testing, and agent-native reviewers did not return before synthesis was required; the correctness/adversarial/api-contract territory (backward-compat save mechanism, discriminator soundness, scoping) was verified directly by the orchestrator and is reflected above. The source: '' emptiness and cross-team isolation items would benefit from a follow-up pass by those personas.

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

Comment thread packages/common-utils/src/types.ts Resolved
Comment thread packages/common-utils/src/types.ts Resolved
PromQL lookups are now keyed by source ID alone, so editing a source's table left the old table's values cached. Also drop the banner comment in the prometheus router.
Comment thread packages/common-utils/src/types.ts Resolved
Comment thread packages/app/src/source.ts Resolved

@brandon-pereira brandon-pereira left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

LGTM thanks!

@kodiakhq
kodiakhq Bot merged commit c94d12c into main Oct 14, 2026
29 checks passed
@kodiakhq
kodiakhq Bot deleted the agent/backport-promql-source-refactor branch October 14, 2026 16:56

This branch was successfully deployed

2 active deployments
Preview – hyperdx-oss — d1ff56a9 Deployed Oct 14, 2026 by vercel[bot]
Preview – hyperdx-storybook — d1ff56a9 Deployed Oct 14, 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-3 Standard — full human review required

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants