Skip to content

feat: Support heatmaps on prometheus histograms - #3332

Merged
pulpdrew merged 2 commits into
mainfrom
drew/heatmap-promql-histogram
Oct 14, 2026
Merged

pulpdrew merged 2 commits into
mainfrom
drew/heatmap-promql-histogram

Conversation

@pulpdrew

@pulpdrew pulpdrew commented Oct 8, 2026

Copy link
Copy Markdown
Contributor

Summary

This PR adds a new heatmap mode ("histogram") for Prometheus metrics intended to support displaying pre-bucketed histogram-type data as a heatmap.

This is a distribution-type histogram (y-axis is numeric buckets, color is count of observations), but with the buckets pre-computed in the metric. The bounds are taken from the le (less than or equal to) labels on each metric, and the counts are the (de-accumulated) values of the metric.

Users should sum by (le) (...expression) to sum by bounds across series.

Screenshots or video

Screenshot 2026-10-08 at 1 32 44 PM Screenshot 2026-10-08 at 1 57 19 PM

How to test locally

  • Create a promql data source on the metrics_ts timeseries table
  • Create a heatmap chart in histogram mode

References

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

@changeset-bot

changeset-bot Bot commented Oct 8, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: df47699

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

@github-actions

github-actions Bot commented Oct 8, 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 · 🟠 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. No finding blocks merge automatically; a maintainer decides.

@greptile-apps

greptile-apps Bot commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 5/5

[Medium impact] The PR appears safe to merge; no new actionable issue was established.

Summary

Adds PromQL histogram heatmaps with one row per le bucket and colors based on each bucket's value.

  • PromQL heatmaps turn cumulative histogram buckets into separate rows.
  • The PromQL editor offers Histogram mode and an example bucket query.
  • Histogram heatmaps label bucket rows and show their ranges on hover.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Histogram mode] --> B[PromQL range query]
  B --> C[Check le labels]
  C --> D[Sort bucket bounds]
  D --> E[Subtract lower bucket counts]
  E --> F[Draw bucket rows and tooltips]
Loading

Reviews (6) · Last reviewed commit: "fix: Fix gaps between heatmap cells" · Reviewed by Greptile

@pulpdrew
pulpdrew force-pushed the drew/heatmap-promql-histogram branch from cc8eaa1 to 15bc2b3 Compare October 8, 2026 18:15
@vercel

vercel Bot commented Oct 8, 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 13, 2026 11:51pm UTC
hyperdx-storybook Ready Ready Preview Oct 13, 2026 11:51pm UTC

Request Review

@github-actions

github-actions Bot commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

Deep Review

Scope: PromQL histogram heatmap mode — new le-bucket grid builder, bucket-axis formatting, query shaping, UI mode control, and a cell-rounding change. Base 1a191fd6, 40 files, +1358/−180.

Intent (soft framing): render pre-bucketed Prometheus histograms as a distribution heatmap, one row per le bound, cells = de-accumulated cumulative counts.

Most of the prior review thread is already resolved in the current code: the non-monotonic de-accumulation inflation (below = Math.max(below, cum)), the false 0 lower bound on the lowest bucket (≤ hi), and the small-rate precision loss in the tooltip (maximumSignificantDigits: 3) are all fixed. The decimal-precision axis-label concern was withdrawn by the prior reviewer as an intentional user-controlled setting.

🟡 P2 — recommended

  • packages/app/src/components/DBHeatmapChart/heatmapPaths.ts:61 — Snapping all four cell edges to integer pixels (added in this PR to remove antialiased seams) collapses any cell narrower or shorter than one pixel to zero area, so a populated bucket/time cell silently vanishes rather than leaving a seam.
    • Fix: Clamp drawn width and height to at least one pixel when the cell has a non-empty fill index.
🔵 P3 nitpicks (2)
  • packages/app/src/components/DBHeatmapChart/heatmapAxis.ts:98 — formatBucketBound forwards average: true into formatNumber, so very large bounds may render in compacted form (1K) on the axis while adjacent compacted bounds can collide visually; acceptable for ticks but worth confirming against the intent that "adjacent bounds like 2.5 and 5 must not round to the same label."
    • Fix: Confirm compaction never merges two distinct adjacent bounds into the same label, or disable average for bound labels.
  • packages/app/src/components/DBHeatmapChart/heatmapHistogram.ts:21 — stepMs falls back to 0 for a single time bucket, which leaves time indexing dependent on makeTimeIndexer's zero-step behavior.
    • Fix: Add an explicit single-bucket test and confirm the zero-step path maps the lone sample correctly.

Reviewers (8 dimensions): correctness, testing, maintainability, typescript, performance, adversarial, previous-comments, project-standards. Findings were verified directly against the current diff and the prior-comment thread.

Testing gaps:

  • Confirm computeBucketPercentiles is exercised for the new buckets y-axis grid (HeatmapPlot.tsx changed its guard from === 'numeric' to !== 'series'), since bucket-mode percentiles are a newly reachable path.
  • Confirm heatmapHistogram has a test for a decreasing intermediate cumulative bucket followed by a higher one (the exact non-monotonic case the de-accumulation Math.max guards against).
  • Confirm toHistogramRows error paths (missing le, duplicate exact le string) surface as a chart error rather than an unhandled rejection.

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

@pulpdrew
pulpdrew requested review from a team, SpencerTorres and karl-power and removed request for a team and SpencerTorres October 8, 2026 20:57
@pulpdrew
pulpdrew added this pull request to stack #3340 October 9, 2026 12:02
@github-actions

github-actions Bot commented Oct 9, 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 125 in total (1.74%).
Run yarn dupes locally to reproduce, or yarn dupes:all for the full picture.

@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

E2E Test Results

✅ All tests passed • 410 passed • 1 skipped • 1324s

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

Tests ran across 4 shards in parallel.

View full report →

@pulpdrew
pulpdrew force-pushed the drew/heatmap-promql-histogram branch from 947f2ae to ba5d7a4 Compare October 9, 2026 13:06
@github-actions github-actions Bot added the review/tier-3 Standard — full human review required label Oct 9, 2026
@github-actions

github-actions Bot commented Oct 9, 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: 775 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: 23
  • Production lines changed: 775 (+ 757 in test files, excluded from tier calculation)
  • Branch: drew/heatmap-promql-histogram
  • 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.

}
return numberFormat
? formatNumber(bound, { ...numberFormat, average: true })
: COMPACT_NUMBER_FORMAT.format(bound);

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 — Bucket bounds with no number format are rounded to 2 significant digits, so adjacent bounds can share a label

The doc comment says this keeps the digits that tell adjacent bounds apart, but notation: 'compact' with no digit options rounds to 2 significant digits. Bounds 1000/1050/1100 come out as 1K/1.1K/1.1K, so the tooltip reads 1.1K – 1.1K, and 2.25 is shown as 2.3. Use a bound-specific formatter instead, e.g. compact notation with maximumSignificantDigits: 4 (or roundingPriority: 'morePrecision' with maximumFractionDigits), and add a test case such as formatBucketRange([1000, 1050, 1100], 2, …).

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

Number(await heatmap.hoveredTooltipValue('Count Value')),
).toBeGreaterThan(0);
expect(await heatmap.hoveredTooltipValue('Bucket')).toMatch(
/^(0 – 0\.1|0\.1 – 0\.5|0\.5 – 1|> 1)\b/,

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 — The e2e bucket regex expects a lowest-bucket label the code never produces

formatBucketRange labels row 0 ≤ 0.1 (see the unit test in heatmapAxis.test.ts), not 0 – 0.1. The test passes only because hoverPopulatedCell scans from the top and hits the > 1 row first. Change the alternative to ≤ 0\.1 so the assertion still holds if hover order or the seed data changes.

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

}) {
const options = allowHistogram ? PROMQL_MODE_OPTIONS : BUILDER_MODE_OPTIONS;
const isOfferedMode = (value: string): value is M =>

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 — The generic M and the allowHistogram flag can disagree, so the type guard is unsound

<HeatmapModeControl<HeatmapMode> allowHistogram onModeChange={…}> type-checks, but isOfferedMode would narrow 'histogram' to HeatmapMode and pass it to a builder handler. Derive the options from the type instead, e.g. overloads or a discriminated prop ({ allowHistogram: true; onModeChange: (m: PromqlHeatmapMode) => void } | { allowHistogram?: false; onModeChange: (m: HeatmapMode) => void }), so an invalid combination can't be written.

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

@pulpdrew
pulpdrew merged commit 3bedfab into main Oct 14, 2026
30 checks passed

This branch was successfully deployed

2 active deployments
Preview – hyperdx-oss — df47699c Deployed Oct 13, 2026 by vercel[bot]
Preview – hyperdx-storybook — df47699c Deployed Oct 13, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review/tier-3 Standard — full human review required

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants