feat: Add completions for PromQL variables

[pulpdrew]

Summary

This PR improves support for variables in promql by adding variable reference completions to the promql editor.

Note that this requires enabling the following feature toggles:

(In the UI)

• NEXT_PUBLIC_ENABLE_PROMQL=true
• NEXT_PUBLIC_ENABLE_DASHBOARD_VARIABLES=true

(In the API)

• ENABLE_PROMQL=true

Screenshots or video

Screen.Recording.2026-08-25.at.12.23.03.PM.mov

How to test

• Create a PromQL source, the default.metrics_ts timeseries table should exist after enabling promql
• Create a dashboard and add a variable that queries instance IDs ResourceAttributes['service.instance.id'] from the metrics gauge table
• Create a promql tile that references a variable, eg. http_client_duration_milliseconds_count{instance=~"$Instance"}

References

• Linear Issue: Related to HDX-5064
• Related PRs:

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ready	Preview	Aug 26, 2026 6:12pm
hyperdx-storybook	Ready	Preview	Aug 26, 2026 6:12pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 91147c2

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/app	Patch
@hyperdx/api	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

[greptile-apps]

Greptile Summary

This PR adds language-specific PromQL variable completions, integrates them with metric and built-in PromQL suggestions, and adds unit and end-to-end coverage. The new replacement-range handling still misclassifies an existing braced reference when the cursor is directly after its $, causing completion acceptance to produce malformed query text.

• Adds PromQL-specific variable completion entries and expansion previews.
• Preserves SQL- and Lucene-specific completion behavior.
• Adds a dedicated completion source that replaces the reference around the cursor.
• Extends unit and dashboard-variable end-to-end tests.

Confidence Score: 4/5

The PR should not merge until accepting a completion at the $|{name} boundary preserves the complete existing variable reference.

The completion source classifies reference form using only text before the cursor, so an existing braced reference with the cursor after $ receives a bare replacement range and becomes malformed when a braced completion is accepted.

Files Needing Attention: packages/app/src/components/PromQLEditor/variableCompletionSource.ts and its range tests

Important Files Changed

Filename	Overview
packages/app/src/components/PromQLEditor/variableCompletionSource.ts	Adds reference-aware replacement ranges, but misclassifies a braced reference when its opening brace is immediately after the cursor.
packages/app/src/components/PromQLEditor/PromQLEditor.tsx	Registers variable, metric-name, and built-in PromQL completion sources through a reconfigurable autocomplete compartment.
packages/app/src/components/SQLEditor/variableCompletions.tsx	Separates SQL and PromQL completion generation and previews each form using language-aware substitution.
packages/common-utils/src/variables.ts	Extends shared variable substitution with PromQL-specific default formatting.
packages/app/src/components/PromQLEditor/tests/variableCompletionSource.test.ts	Covers suffix preservation and several cursor positions but omits the `$

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A["Cursor in $|{env}"] --> B["Completion source sees only $ before cursor"]
  B --> C["Selects bare-reference suffix matcher"]
  C --> D["Replacement range covers only $"]
  D --> E["Accept ${env} completion"]
  E --> F["Query becomes ${env}{env}"]

Loading

_{Reviews (4): Last reviewed commit: "feat: Add completions for PromQL variabl..." | Re-trigger Greptile}

[greptile-apps]

Replacement range consumes query suffixes

When a user accepts a completion while editing a reference followed by valid PromQL text, such as ${sv}_total, VARIABLE_AFTER includes the closing brace and _total in the replacement range, causing the suffix to be silently deleted and changing the query.

Knowledge Base Used: Dashboards and visualization

[github-actions]

E2E Test Results

✅ All tests passed • 318 passed • 1 skipped • 1172s

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

Tests ran across 4 shards in parallel.

View full report →

[github-actions]

🟡 Tier 3 — Standard

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

Why this tier:

• Diff size: 254 production lines changed (Tier 2 max: < 250)
• Cross-layer change: touches frontend (packages/app) + shared utils (packages/common-utils)

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

Stats

• Production files changed: 6
• Production lines changed: 254 (+ 452 in test files, excluded from tier calculation)
• Branch: drew/promql-variable-completions
• Author: pulpdrew

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]

Deep Review

✅ No critical issues found. The core change — a dedicated CodeMirror completion source for PromQL variable references plus a clean SQL/PromQL split of the variable-completion builders — is correct and well-covered by unit and E2E tests. The refactor preserves the existing SQL completion output (macros, every reference form, and expansion previews are reproduced field-for-field), and the editor wiring correctly re-registers PromQL's own function/keyword source that an override array would otherwise drop.

Prior review comment — resolved. The earlier P1 ("replacement range consumes query suffixes", e.g. ${sv}_total) is addressed by this diff. The range logic now lives in packages/app/src/components/PromQLEditor/variableCompletionSource.ts, where VARIABLE_AFTER_BRACED (/^[\w:]*\}?/) stops at the first }, and variableCompletionSource.test.ts asserts the exact ${env}_total case (to: 6, _total preserved). No open action.

🔵 P3 nitpicks (2)

• packages/app/src/components/PromQLEditor/variableCompletionSource.ts:25 — VARIABLE_AFTER_BRACED (/^[\w:]*\}?/) assumes a closing brace exists; for a malformed unclosed reference with trailing word characters (e.g. ${svc_total with no }), it greedily consumes the trailing text, so accepting a completion would swallow it. Auto-close normally guarantees the brace, so this is an edge case, but it is untested.
  • Fix: Add a test for the unclosed-brace-with-suffix case and confirm the intended behavior, bounding consumption if suffix loss is not wanted.
• packages/app/src/components/PromQLEditor/PromQLEditor.tsx:121 — re-registering the built-in source via promqlExtension.getComplete().promQL(context) couples the editor to an internal API of the PromQL CodeMirror package that could change on upgrade; the risk is mitigated by an E2E assertion that rate still completes and an explanatory comment.
  • Fix: Keep the E2E guard and consider pinning/asserting the package version so an upgrade that removes getComplete() fails loudly.

---

Reviewers (9): correctness, testing, maintainability, project-standards, kieran-typescript, julik-frontend-races, previous-comments, agent-native, learnings.

Residual risks: Built-in PromQL completions depend on the third-party getComplete().promQL internal API (guarded only by E2E). No agent-native gap — this is an editor-UX affordance with no separate agent-reachable surface.

Testing gaps: Unit tests omit the braced-with-format-then-text case (${svc:regex}_total), a bare reference immediately followed by { ($svc{...}), and the unclosed-brace edge above; the happy paths and the previously-reported suffix case are covered.