Skip to content

feat: Accept optional time bounds on Prometheus label values endpoint - #3039

Merged
kodiakhq[bot] merged 3 commits into
mainfrom
drew/promql-lable-values-bounded
Sep 1, 2026
Merged

kodiakhq[bot] merged 3 commits into
mainfrom
drew/promql-lable-values-bounded

Conversation

@pulpdrew

@pulpdrew pulpdrew commented Aug 31, 2026 •

Copy link
Copy Markdown
Contributor

Summary

This PR updates the prometheus /values endpoint with optional start and end parameters, representing timestamps used to filter for label values in a particular time range.

  • On the proxy path, the parameters are now forwarded to Prometheus
  • On the ClickHouse path, the parameters are used as WHERE conditions when querying timeSeriesTags. The timeSeriesTags min_time and max_time columns are optional, so we first query to determine if the columns exist before filtering on them.

This PR also refactors the endpoint a bit to (a) use zod for validation and (b) relocate queries into metadata and a new timeseriesEngine controller file.

These filters are best-effort (because the min and max time columns are optional) and approximate (because we check only min/max timestamps, it's possible that a sample occurring only before start and after end is included).

Screenshots or video

UI still successfully queries label values for metric name selector autocomplete

Screenshot 2026-08-31 at 10 31 17 AM Screenshot 2026-08-31 at 10 31 46 AM

Request with start/end applies filter:

Screenshot 2026-08-31 at 10 33 17 AM Screenshot 2026-08-31 at 10 33 32 AM

How to test locally

  1. Create a promql / timeseries source
  2. View a chart based on the timeseries source and capture the /values request from the network tab.
  3. Add time range parameters to it and send the request with eg. curl

References

  • Linear Issue: Closes HDX-5234
  • Related PRs:

@changeset-bot

changeset-bot Bot commented Aug 31, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: d74a56f

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

@vercel

vercel Bot commented Aug 31, 2026 •

Copy link
Copy Markdown

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

2 Skipped Deployments
Project Deployment Actions Updated
hyperdx-oss Ignored Ignored Preview Sep 1, 2026 10:02am UTC
hyperdx-storybook Ignored Ignored Preview Sep 1, 2026 10:02am UTC

Request Review

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

github-actions Bot commented Aug 31, 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: 418 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: 5
  • Production lines changed: 418 (+ 800 in test files, excluded from tier calculation)
  • Branch: drew/promql-lable-values-bounded
  • 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.

@greptile-apps

greptile-apps Bot commented Aug 31, 2026 •

Copy link
Copy Markdown
Contributor

Greptile Summary

The PR adds optional time bounds to Prometheus label-value requests and applies them to both upstream Prometheus and ClickHouse-backed queries.

  • Validates and normalizes label-value request parameters with Zod.
  • Preserves repeatable match[] selectors when proxying to Prometheus and explicitly rejects unsupported selectors on the ClickHouse path.
  • Adds TimeSeries metadata inspection and bounded label-value queries with fallback for tables lacking time-bound columns.
  • Updates the app client and adds integration coverage for validation, forwarding, filtering, limits, and compatibility behavior.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the current handler preserves single and repeated selectors under the upstream match[] key, resolving the previously reported issue.

Important Files Changed

Filename Overview
packages/api/src/routers/api/prometheus.ts Validates label-value parameters, preserves repeatable upstream selectors, routes bounded queries by backend, and completes the previously requested selector-forwarding fix.
packages/api/src/controllers/timeseriesEngine.ts Adds parameterized ClickHouse label-value queries with optional time filtering, limits, and compatibility fallback when bound columns are unavailable.
packages/common-utils/src/core/metadata.ts Adds cached discovery of columns exposed by ClickHouse TimeSeries inner-table functions.
packages/app/src/api.ts Extends the browser label-values client to send optional start and end parameters.
packages/api/src/routers/api/tests/prometheus.int.test.ts Covers normalized bounds, selector forwarding, invalid inputs, limits, and ClickHouse-backed route behavior.
packages/api/src/controllers/tests/timeseriesEngine.int.test.ts Covers bounded and unbounded TimeSeries tables, label types, overlap filtering, parameterization, and result limits.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Client[Label-values request] --> Validate[Validate and normalize parameters]
  Validate --> Backend{Connection backend}
  Backend -->|Prometheus| Proxy[Forward start, end, limit, and match selectors]
  Proxy --> Prometheus[Upstream Prometheus]
  Backend -->|ClickHouse| Metadata[Inspect TimeSeries tags columns]
  Metadata --> Query[Query distinct label values]
  Query --> Filter[Apply available min/max time bounds]
Loading

Reviews (8): Last reviewed commit: "Merge branch 'main' into drew/promql-lab..." | Re-trigger Greptile

@github-actions

github-actions Bot commented Aug 31, 2026 •

Copy link
Copy Markdown
Contributor

Deep Review

Scope: b917308d..HEAD — optional time bounds on the Prometheus /label/:name/values endpoint, with a zod-validated query schema, a new timeseriesEngine controller, and getTimeSeriesTableColumns metadata inspection.
Intent: Add best-effort start/end filtering to label-value lookups on both the Prometheus proxy path and the ClickHouse TimeSeries path, refactoring validation and query construction along the way.

Most prior-review feedback has been addressed in this diff: match[] is now forwarded on the proxy path, parseTimestamp failures route through safeParse instead of the catch-all, connectionId uses objectIdSchema, and inverted ranges are rejected by a superRefine before either backend runs. No P0/P1 issues remain.

✅ No critical issues found.

🟡 P2 — recommended

  • packages/api/src/controllers/timeseriesEngine.ts:77 — Reading only the tags map returns an empty set for any label the TimeSeries table promotes to its own column via tags_to_columns, so /label/<promoted>/values answers 200 {"data":[]} that autocomplete trusts as authoritative rather than erroring; this configuration is untested.
    • Fix: When the already-fetched Tags-table column list contains labelName, select that column directly and drop the mapContains guard; otherwise fall back to tags[labelName].
    • correctness, previous-comments
  • packages/api/src/controllers/timeseriesEngine.ts:85 — Constructing new Metadata(client, new MetadataCache()) inside queryLabelValues discards the cache each call, so getTimeSeriesTableColumns.getOrFetch never hits and every bounded request issues an extra DESCRIBE TABLE timeSeriesTags(...) round trip before the real query.
    • Fix: Hoist the MetadataCache to module scope or use the shared getMetadata(client) helper so the column lookup is cached across requests.
    • performance, maintainability, previous-comments
🔵 P3 nitpicks (5)
  • packages/app/src/api.ts:649 — The new start/end params on prometheusApi.labelValues have no caller (usePromqlMetricNames forwards neither), so the app-side change is unreachable and the changeset's @hyperdx/app patch is presently a no-op.
    • Fix: Drop the params until a caller exists, or wire them through the hook and add them to its react-query key so a range change does not serve the prior range's cached values.
  • packages/api/src/routers/api/prometheus.ts:799 — formatQueryParamIssues is a third copy of the existing path: message zod-issue renderers (formatZodIssues, formatZodError), differing only in join separator.
    • Fix: Import an existing formatter or hoist one shared helper and use it at all three sites.
  • .changeset/promql-label-values-time-range.md:1 — packages/common-utils/src/core/metadata.ts gains the exported getTimeSeriesTableColumns method but the changeset bumps only @hyperdx/api and @hyperdx/app.
    • Fix: Add a @hyperdx/common-utils entry so the published package version reflects the new API surface.
  • packages/api/src/routers/api/__tests__/prometheus.int.test.ts:1 — The ClickHouse-backed router suite re-tests queryLabelValues behavior (bounds, lone bound, limit, unbounded fallback) already covered by the controller suite, and the store_min_time_and_max_time = 0 comment sits above the limit test rather than the fallback test it describes.
    • Fix: Scope the router suite to what only it exercises (seconds→ms conversion, query-string parsing) and move the misplaced comment.
  • packages/common-utils/src/__tests__/metadata.int.test.ts:1 — The cache-count assertions rely on an earlier describe having warmed the module-level settings cache, so running this block in isolation makes the counts off by one.
    • Fix: Assert specifically on DESCRIBE/timeSeriesTags calls filtered from the query spy rather than raw call counts.

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

Testing gaps: The tags_to_columns promoted-label case (empty-result path) has no coverage; proxy-path limit=0 normalization is exercised only on the ClickHouse side.

@github-actions

github-actions Bot commented Aug 31, 2026 •

Copy link
Copy Markdown
Contributor

E2E Test Results

✅ All tests passed • 326 passed • 1 skipped • 1355s

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

Tests ran across 4 shards in parallel.

View full report →

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

github-actions Bot commented Aug 31, 2026 •

Copy link
Copy Markdown
Contributor

PR Review

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

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


Severity is the reviewer's own estimate and is used for ordering, not filtering.

Comment thread packages/app/src/api.ts Resolved
Comment thread packages/app/src/api.ts Resolved
Comment thread packages/app/src/api.ts Resolved
Comment thread packages/app/src/api.ts Resolved
@kodiakhq
kodiakhq Bot merged commit bcf0257 into main Sep 1, 2026
41 of 43 checks passed
@kodiakhq
kodiakhq Bot deleted the drew/promql-lable-values-bounded branch September 1, 2026 10:53
kodiakhq Bot pushed a commit that referenced this pull request Nov 18, 2026
…hreads (#3464)

## Summary

Today the review bot posts **every** finding it can anchor as an inline thread, at every severity, labelled with its own `critical`/`major`/`minor` self-estimate. Apart from #3138 (triage guidance for the author's agent), the reviewer has not changed since #3024.

This PR adds a separate grading pass that assigns each finding a priority, posts only P0–P2 inline, and folds P3 into the sticky summary. It also stops reworded findings from being re-posted as new threads on later pushes.

## Production today vs this PR

| | production (`main`) | this PR |
|---|---|---|
| Label users see | reviewer's own severity: 🔴 critical · 🟠 major · 🔵 minor | priority only: 🔴 P0/P1 · 🟡 P2 · 🔵 P3 (same icons as deep-review) |
| Inline threads | every anchored finding | P0–P2 |
| Folded into the summary | only `minor` findings that could not be anchored | every P3, anchored or not. Folded, never dropped |
| Grading | none | a second pass (Sonnet, `Read` only) grades the finished findings. It cannot add, drop or reword them |
| Reworded finding on a later push | opens a new thread (dedup keyed on the exact title) | recognised as the same finding |
| Grading fails | n/a | nothing is folded; the review posts exactly as on `main` |

### How a finding's priority is decided (`effectivePriority` in `priority.cjs`)

A finding is folded only when **both** graders call it low, and nothing says it matters today:

- the reviewer itself labelled it `minor`, **and**
- the grading pass put it at P2 or P3, **and**
- the grader doesn't say the harm is reachable in the merged code, **and**
- it doesn't read as security-related.

Neither grader can fold anything on its own: a grader P3 on a finding the reviewer called major or critical is shown as P2. Without a grade, nothing is folded (critical → P0, major → P1, minor → P2).

## Measured against human votes

Data: 👍/👎 reactions maintainers left on this bot's inline comments, covering **75 graded findings across 29 PRs** (53 👍, 22 👎) from 4 maintainers. Two kinds of vote are excluded: reactions cast by bots, and "blanket" votes, where one person thumbed ≥10 findings on a PR without a single 👎. The "this PR" column comes from running this branch's `effectivePriority` over the grading pass's output.

| | production | this PR |
|---|---|---|
| Inline threads | 75 / 75 | **49 / 75** |
| Folded as P3 | 0 | **26 (35%)** |
| 👍 major/critical findings still inline | 17 / 17 | **17 / 17** |
| 👎 findings folded | 0 / 22 | 8 / 22 |
| 👍 findings folded | 0 | 18, all ones the reviewer labelled `minor` |

So, on this sample, about a third fewer inline threads, with no upvoted major/critical finding hidden. The cost is 18 upvoted minor findings moving from inline threads into the folded section of the summary.

## Checked against the gold set

The vote data can only see the severity the bot assigned. It can't tell whether a folded finding was one a human treated as **must-fix**. That's what the gold set measures. It contains human review comments on 30 past PRs (93 items, 29 of them must-fix). The deployed reviewer's findings on those PRs were re-graded with this PR's grading prompt and routed with this PR's rule, reusing the existing match judgements.

| | production | this PR | same rule, no reachable-today floor |
|---|---|---|---|
| Inline threads | 122 (4.1/PR) | **93 (3.1/PR)** | 70 (2.3/PR) |
| Must-fix items the reviewer caught | 10/29 | 10/29 | 10/29 |
| …of those, folded out of the inline threads | 0 | **0** | **3** |

Must-fix recall can't move, because grading never changes what was found. The column to read is the last row. The grader rated 3 of the 10 caught must-fix items P2, and the reviewer had labelled all 3 `minor`, so the minor-P2 fold alone would have hidden them:

- #1410: deep-linked equality/range filters are silently dropped from the filter sidebar
- #2604: OpenAPI spec not regenerated for the new tile type
- #2696: `getRecentAlertGroupSummaries` has no DB-side document cap, unlike its sibling

The reachable-today floor is what keeps all three inline. On this data it is the difference between hiding 0 and 3 of the 10.

## Dedup fix

The cross-push dedup key was `file + exact title`, on the assumption that titles are stable between runs. They aren't. #3039 was reviewed four times in 2.3 hours, and one defect was posted three times under three titles; all three were thumbed down. Restatements are now matched by title-word overlap within the same file: at least 0.4 overlap **and** at least 3 shared content words. The second condition stops short titles like "Missing timeout in fetchUser" and "Missing retry in fetchUser" from merging.

The threshold (0.4) was set from all 140 same-PR, same-file pairs of voted findings. Every pair scoring 0.36 or higher is a restatement. At 0.333, restatements collide with genuinely distinct findings. On #3129, "signs every user out on each container restart" and "still signs sessions with the public secret" are two real defects (the second critical) at exactly that score. So one known reword on #3039 is still missed rather than risk merging those two. Both cases are verbatim test fixtures.

## Limits and what isn't measured yet

- **The gold-set result rests on 10 caught must-fix items** from one reviewer run (Sonnet; production runs Opus). Zero folded is the bar, but each item is worth 10 points.
- **The votes are sparse and uneven.** There are 22 👎, mostly from two people whose thresholds differ ~4×, and only 1 of 197 voted comments has more than one reactor.
- **The reachable-today floor costs volume.** In the vote sample it didn't separate 👍 from 👎 (~30% 👎 either way), and it lowers the fold rate there from 52% to 35%. On the gold set it is what keeps all 3 at-risk must-fix items visible, so the cost buys something.
- **Premise findings.** The grading prompt describes findings that object to the change's premise as "published in their own section". This PR does not build that section; those findings are routed by priority like any other.
- **Cost:** one more Sonnet call per reviewed push that has at least one finding. Not yet measured in CI.
- **This PR's own review runs the old workflow,** because `pull_request_target` loads it from `main`. To exercise the new path before merge, dispatch **Claude Code Review** from this branch against an open PR.

## Test plan

- [x] `node --test .github/scripts/code-review/__tests__/*.test.mjs`: 58/58. The priority rule and the title dedup live in `priority.cjs` and `dedup.cjs`.
- [x] Workflow YAML parses; Prettier and knip clean on the changed files
- [x] Ran the helpers over a real PR's findings and grades (#3258: 7 findings → 4 shown, 3 folded)
- [ ] Dispatch from this branch on 2–3 open PRs and check the inline/folded split
- [x] Gold-set check: 0 of 10 caught must-fix items folded (3 without the reachable-today floor)

## Also tried (not in this PR)

- **The reviewer assigning P0–P3 itself, in a single pass.** Its grades were better calibrated, but it caught 7/29 must-fix items against 10/29 (one run each, so possibly noise).
- **Folding all P2s, not just minor ones.** This hid 61% of comments but lost 4 of the 17 upvoted major/critical findings.
- **Folding on the reviewer's `minor` label alone.** On the gold set it hid 46% of the findings humans treated as merge-blocking.
- **Using `reachableToday` as the main signal.** It didn't distinguish 👍 from 👎 in the votes, so here it only acts as a floor. As a floor, it's what protects must-fix items on the gold set.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
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