Skip to content

feat: Document PromQL tiles and reject PromQL sources when PromQL is disabled in the external API - #3416

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

karl-power merged 6 commits into
mainfrom
claude/promql-external-api-docs

Conversation

@karl-power

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

Copy link
Copy Markdown
Contributor

Summary

Document PromQL dashboard tiles in the external API OpenAPI spec, and reject creating PromQL sources while PromQL is disabled.

  • Add configType: "promql" variants for line, stacked_bar, stacked_line, table, number, pie, bar, and heatmap tiles, with shared schemas for expressions and common fields, matching what /api/v2/dashboards accepts and returns since feat: Support PromQL dashboard tiles in the external API #3379.
  • Fix the PromqlSource description, which said the connection must be a Prometheus endpoint and that from is unused. A PromQL source can also read a ClickHouse TimeSeries table, where from names the table.
  • Note in the PromQL source, tile and label filter docs that PromQL is a preview feature that must be enabled (ENABLE_PROMQL).
  • POST and PUT /api/v2/sources return a 400 for kind: "promql" when ENABLE_PROMQL is off, since those sources cannot be queried. Other source kinds are unaffected.
  • Regenerate packages/api/openapi.json.

How to test

  1. Run yarn workspace @hyperdx/api lint:openapi: no errors.
  2. Open /api/v2/docs on the running API and check that each dashboard tile display type lists a PromQL variant, and that the PromqlSource schema describes both connection types.
  3. With ENABLE_PROMQL unset, POST /api/v2/sources with kind: "promql": 400, “PromQL is not enabled on this deployment”.

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:33pm UTC
hyperdx-storybook Ready Ready Preview Oct 22, 2026 12:33pm UTC

Request Review

@changeset-bot

changeset-bot Bot commented Oct 20, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 72f7e7c

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

@karl-power
karl-power added this pull request to stack #3415 October 20, 2026 12:24
@karl-power
karl-power force-pushed the claude/promql-external-api-docs branch from 346f8f8 to 0a19268 Compare October 20, 2026 12:24
@github-actions

github-actions Bot commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

E2E Test Results

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

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

Tests ran across 4 shards in parallel.

View full report →

@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.

@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 two non-blocking documentation corrections still open.

Fix All in Claude CodeFindings

  1. P2 Unlimited charts still stop ▶
  2. P2 Aliases replace single-series names ▶

Summary

Adds PromQL tile schemas to the external API docs and regenerates openapi.json.

  • The API spec now shows PromQL options for dashboard tiles.
  • PromQL source writes stop when the feature is off.
  • PromQL sources now describe both supported connection types.

Reviews (9) · Last reviewed commit: "fix: Reject PromQL sources in the extern..." · Reviewed by Greptile

@karl-power
karl-power marked this pull request as ready for review October 20, 2026 15:05
@github-actions github-actions Bot added the review/tier-4 Critical — deep review + domain expert sign-off label Oct 20, 2026
@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 (2) — tenancy, public API, or shipped database config:
    • packages/api/src/routers/external-api/v2/dashboards.ts
    • packages/api/src/routers/external-api/v2/sources.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: 3
  • Production lines changed: 1022 (+ 49 in test files, excluded from tier calculation)
  • Critical-path lines changed: 460
  • Branch: claude/promql-external-api-docs
  • 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.

@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.

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

1 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

✅ No critical issues found.

This is a documentation-only change: OpenAPI JSDoc annotations in two router files plus the regenerated packages/api/openapi.json. I verified every documented enum, constant, default, field name, and pattern against the authoritative Zod schema and runtime code, and confirmed the generated spec is in sync.

Accuracy spot-checks (all pass):

  • PromQL variant field names, configType discriminators, and allOf composition match externalDashboardPromqlTileConfigSchema in packages/api/src/utils/zod.ts.
  • reducer enum, queryType enum/default (range), heatmapMode, heatmapScaleType, maxItems: 10 (MAX_PROMQL_EXPRESSIONS), and maxLength: 1024 (MAX_LEGEND_TEMPLATE_LENGTH) all match the Zod source.
  • granularity pattern ^(\d+ (second|minute|hour|day)|auto)$ correctly mirrors SQLIntervalSchema plus the auto literal.
  • The reducer note that it "also applies to instant queries" matches displayTypeSupportsReducer semantics in packages/common-utils/src/core/promql.ts.
  • openapi.json contains all new schemas and its content matches the JSDoc blocks.

🟡 P2 -- recommended

None.

🔵 P3 nitpicks (1)
  • packages/api/src/routers/external-api/v2/dashboards.ts:1577 -- The new PromQL tile and PromqlSource docs do not state that PromQL is a preview capability that may need to be enabled before PromQL sources and tiles can be created, which a reviewer flagged on the prior approval.
    • Fix: Add a sentence to the PromqlSource and PromQL chart-config descriptions noting the preview/enablement precondition for creating PromQL sources and tiles.
    • previous-comments, api-contract

Reviewers (6): correctness, api-contract, previous-comments, project-standards, testing, maintainability.

Testing gaps: None for this change — the documented request/response shapes are already exercised by promqlTiles.int.test.ts and the external-api dashboards.int.test.ts suites; documentation edits need no additional coverage.

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

* oneOf:
* - $ref: '#/components/schemas/HeatmapDistributionChartConfig'
* - $ref: '#/components/schemas/HeatmapSeriesChartConfig'
* - $ref: '#/components/schemas/HeatmapPromqlChartConfig'

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 HeatmapChartConfig get a discriminator with a promql mapping, like the other tile groups?

Without one, generated clients have to work out the variant from the fields that are present.

discriminator:
  propertyName: configType
  mapping:
    promql: '#/components/schemas/HeatmapPromqlChartConfig'

pulpdrew
pulpdrew previously approved these changes Oct 22, 2026

@pulpdrew pulpdrew 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, but if we don't already can/should we:

  1. Note in the API that PromQL is a private preview feature and must be enabled before creating promql sources and tiles
  2. Reject requests that create promql sources if the toggle is not enabled?

Add PromQL variants for each tile display type to the OpenAPI schemas,
and correct the PromqlSource description: a PromQL source can read a
ClickHouse TimeSeries table, not only a Prometheus endpoint.
Only line and stacked tiles query every expression; other display types
query the first. Tables have one row per sample, and reducers also apply
to instant queries.
@karl-power
karl-power force-pushed the claude/promql-external-api-docs branch from 5882c49 to 774b13b Compare October 22, 2026 12:28
@karl-power

Copy link
Copy Markdown
Contributor Author

LGTM, but if we don't already can/should we:

  1. Note in the API that PromQL is a private preview feature and must be enabled before creating promql sources and tiles
  2. Reject requests that create promql sources if the toggle is not enabled?

Both good callouts! Especially the second one which I completely missed. Just updated now with one commit for each

@karl-power
karl-power requested a review from pulpdrew October 22, 2026 12:30
@karl-power karl-power changed the title docs: Document PromQL dashboard tiles in the external API spec feat: Document PromQL tiles and reject PromQL sources when PromQL is disabled in the external API Oct 22, 2026
* Shared fields for PromQL chart configs. Set configType to "promql" and
* provide sourceId + expressions. The connection is read from the source.
* PromQL is a preview feature and must be enabled on the deployment
* (ENABLE_PROMQL) before PromQL tiles can be queried.

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.

FYI before merging to EE, ENABLE_PROMQL is misleading for CHC teams - we have a team level sysadmin flag for them, and they don't need to know what it's called. I would just say the feature needs to be enabled.

@github-actions

Copy link
Copy Markdown
Contributor

Deep Review

✅ No critical issues found.

This is a near-documentation PR: ~400 lines of OpenAPI JSDoc for PromQL dashboard tiles plus the regenerated packages/api/openapi.json, and one small functional change — a rejectPromqlSourceWhenDisabled middleware that returns 400 for kind: "promql" source writes unless ENABLE_PROMQL is set. The middleware was verified correct: it reads the Zod-validated body, covers both the POST and PUT write paths (the only source-mutating external routes), and its config.IS_PROMQL_ENABLED namespace read is live, so the tests' jest.replaceProperty takes effect. The input-narrowing (now rejecting promql writes when disabled) is intentional, flag-gated, and documented in the changeset.

🟡 P2 -- recommended

  • packages/api/src/routers/external-api/v2/dashboards.ts:1539 -- The new alias description says it is "Prefixed to every series name," but a single-series expression's alias replaces the name outright and only prefixes the label set when the expression returns multiple series.
    • Fix: Reword alias to document single-series replacement versus multi-series prefix behavior, and regenerate openapi.json.
    • api-contract, previous-comments
🔵 P3 nitpicks (2)
  • packages/api/src/routers/external-api/v2/dashboards.ts:1638 -- The new seriesLimit description says "set 0 for unlimited," but time charts still draw at most 100 series regardless, since 0 only lifts the prepared-data cap, not the final draw ceiling (HARD_LINES_LIMIT); the same wording already exists on the builder and Raw SQL sibling fields.
    • Fix: Note the ~100-series draw ceiling alongside the 0 behavior, applying it consistently with the sibling time-chart docs, then regenerate openapi.json.
    • api-contract, previous-comments
  • packages/api/src/routers/external-api/v2/sources.ts:117 -- The preview gate lives in a route-level middleware rather than in createSource/updateSource, so the invariant must be re-applied by hand on any future source-write route.
    • Fix: Consider enforcing the ENABLE_PROMQL check inside the shared source-write controller, or add a comment noting the gate is applied at the route layer.

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

Testing gaps: Enabled-path coverage of the new gate is only implicit — the pre-existing should create a promql source test relies on ENABLE_PROMQL=true in .env.test, so if that default ever changes the enabled branch silently goes untested rather than failing loudly.

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

@karl-power
karl-power merged commit 27cccf7 into main Oct 22, 2026
36 checks passed
@kodiakhq
kodiakhq Bot deleted the claude/promql-external-api-docs branch October 22, 2026 12:41

This branch was successfully deployed

2 active deployments
Preview – hyperdx-storybook — 72f7e7c7 Deployed Oct 22, 2026 by vercel[bot]
Preview – hyperdx-oss — 72f7e7c7 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