Skip to content

feat: Support series mode on builder heatmaps - #3291

Merged
kodiakhq[bot] merged 3 commits into
mainfrom
drew/heatmap-series-4
Oct 6, 2026
Merged

kodiakhq[bot] merged 3 commits into
mainfrom
drew/heatmap-series-4

Conversation

@pulpdrew

@pulpdrew pulpdrew commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

Summary

This PR adds a new heatmap "mode" in which the y-axis represents unique series (group-by values), the x-axis represents time, and the color is determined by an aggregate value over that group at that time bucket.

This is analogous to a timeseries chart, where instead of plotting the value of each series on the y-axis, the value is plotted on the color axis. Consequently, the builder interface and resulting query looks very similar to those from the time chart implementation.

When too many (>50) series are selected, a warning is shown, and only the top 50 series are shown (by the same math used for client-side time chart series limits.

Notes:

  • MCP and External API support is deliberately missing, will be added in a subsequent PR

The y-axis series labels are truncated when necessary, with a tooltip that shows the full results.

Screenshots or video

Screenshot 2026-10-05 at 9 24 48 AM

How to test on Vercel preview

Create some series-mode heatmaps

References

@changeset-bot

changeset-bot Bot commented Oct 5, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 5b1645f

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

This PR includes changesets to release 4 packages
Name Type
@hyperdx/app Minor
@hyperdx/common-utils Minor
@hyperdx/api Minor
@hyperdx/otel-collector Minor

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 5, 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 6, 2026 11:29am UTC
hyperdx-storybook Ready Ready Preview Oct 6, 2026 11:29am UTC

Request Review

@github-actions github-actions Bot added the review/tier-4 Critical — deep review + domain expert sign-off label Oct 5, 2026
@github-actions

github-actions Bot commented Oct 5, 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/utils/alertChartConfig.ts
    • packages/api/src/routers/external-api/v2/utils/dashboards.ts
  • Cross-layer change: touches frontend (packages/app) + backend (packages/api) + shared utils (packages/common-utils)

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: 30
  • Production lines changed: 1200 (+ 958 in test files, excluded from tier calculation)
  • Critical-path lines changed: 19
  • Branch: drew/heatmap-series-4
  • Author: pulpdrew

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 5, 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 128 in total (1.79%).
Run yarn dupes locally to reproduce, or yarn dupes:all for the full picture.

@greptile-apps

greptile-apps Bot commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 4/5

[Medium risk] Adds series mode to heatmap charts in the builder.

The PR needs the plotting component split to satisfy the repository’s component-size requirement before merging.

Fix All in Claude CodeFindings

  1. P2 Heatmap component exceeds size limit ▶

Summary

The PR adds series-mode builder heatmaps alongside numeric distribution heatmaps.

  • It adds mode-specific editor controls, queries, rendering, and tests while retaining distribution behavior for older charts.
  • It leaves series-mode external API support to the subsequent PR.
Diagram
%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Builder heatmap] --> B{Mode}
  B -->|Distribution| C[Bounds query]
  C --> D[Bucketed-count query]
  D --> E[Numeric y-axis]
  B -->|Series| F[Time-chart query]
  F --> G[Group-by rows]
  G --> H[Series y-axis]
Loading

Reviews (5) · Last reviewed commit: "Merge branch 'main' into drew/heatmap-se..."

@pulpdrew
pulpdrew force-pushed the drew/heatmap-series-4 branch from fcc7298 to a62bc4a Compare October 5, 2026 13:34
@github-actions

github-actions Bot commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

E2E Test Results

✅ All tests passed • 398 passed • 1 skipped • 1310s

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

Tests ran across 4 shards in parallel.

View full report →

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

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

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

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

Findings outside the changed lines

1 minor
  • 🔵 packages/app/src/components/DBHeatmapChart/ColorLegend.tsx:13 — Color legend's accessible label still says 'count' on series heatmaps, where color encodes an aggregate value → In series mode the cells are aggregate values (cellKind 'value'), not counts, so screen-reader users hear the wrong label. Pass the cell kind to ColorLegend (HeatmapChartView renders it) and say 'low to high value' for series grids.

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

Copy link
Copy Markdown
Contributor

Deep Review

✅ No critical (P0/P1) issues found. The feature is backward-compatible (new heatmap.mode field is optional, legacy tiles resolve to distribution), the previously-flagged nonpositive-value rendering bug is addressed at HEAD (isEmptyHeatmapCell/fills[i] >= 0 now gate both the painter and the hover handler), and the external-API path deliberately guards series-mode tiles instead of corrupting them. The remaining concerns are state-loss-on-mode-switch behaviors and a lossy external-API round-trip, all P2 or below.

🟡 P2 -- recommended

  • packages/api/src/routers/external-api/v2/utils/dashboards.ts:650 -- convertTileToExternalChart returns undefined for series-mode heatmaps and the result is filtered out, so a GET omits the tile; because PUT replaces the entire tiles array, an external read-modify-write silently deletes a persisted series-mode heatmap tile.
    • Fix: Preserve unrecognized/unsupported tiles across the external GET→PUT round-trip (e.g. pass them through opaquely or merge by tile id on write) so automation clients cannot drop them, and track this with the deferred external-API work.
  • packages/app/src/components/DBEditTimeChartForm/EditTimeChartForm.tsx:854 -- onHeatmapModeChange calls applyHeatmapDefaults, which overwrites select/series with a fresh default series on every mode change, so a user who authored an aggregation/value expression in one mode loses it when toggling to another mode and back.
    • Fix: Preserve the existing authored series (aggregation and value expression) across mode switches, applying defaults only when no user-authored series is present.
  • packages/app/src/components/ChartEditor/utils.ts:157 -- normalizeHeatmapFields forces where: '' for series-mode heatmaps, so switching a distribution heatmap that has a where filter into series mode and saving silently drops the filter and persists a chart that queries unfiltered data, with no path to restore the condition.
    • Fix: Carry the authored where condition into the series-mode equivalent (series-level filter) on transition instead of discarding it, or block/warn before dropping a non-empty filter.
🔵 P3 nitpicks (1)
  • packages/app/src/components/DBEditTimeChartForm/EditTimeChartForm.tsx:845 -- This file is well over the component-size guidance in CLAUDE.md and this change adds further mode/source-transition logic to it.
    • Fix: Extract the heatmap mode/source-transition logic (e.g. applyHeatmapDefaults orchestration and the source-swap effect) into a dedicated hook or module.

Reviewers (10): correctness, adversarial, testing, maintainability, kieran-typescript, performance, api-contract, project-standards, previous-comments, frontend-races.

Testing gaps: No test covers the GET→PUT round-trip deletion of a series-mode heatmap tile via the external API; no test asserts that authored series config and where filters survive (or are intentionally cleared on) a distribution↔series mode switch.

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/guards.ts Resolved
Comment thread packages/common-utils/src/guards.ts Resolved
@pulpdrew
pulpdrew requested a review from karl-power October 5, 2026 16:29

@karl-power karl-power 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 don't we want to address this one?

I think it makes the charts striped like this:

Image

@pulpdrew

pulpdrew commented Oct 6, 2026

Copy link
Copy Markdown
Contributor Author

LGTM, but don't we want to address this one?

I think it makes the charts striped like this:

Image

Yes! I have HDX-5619 to address a few granularity related problems with the heatmap

Comment on lines 279 to +307
},
],
};
}, [width, height, tickFormatter, scaleType, palette, hasFilter]);
}, [
width,
height,
tickFormatter,
scaleType,
palette,
hasFilter,
seriesLabels,
cellKind,
]);

const seriesAxisHover = useSeriesAxisHover(uplotRef, seriesLabels);

const highlightedPercentile =
const highlightedRow =
highlightedPoint && rowCount > 0
? bucketPercentiles.get(highlightedPoint.closestIndex % rowCount)
: undefined;
? highlightedPoint.closestIndex % rowCount
: 0;
const highlightedCell: HeatmapTooltipCell | undefined =
highlightedPoint == null
? undefined
: seriesLabels != null
? {
kind: 'series',
name: seriesLabels[highlightedRow] ?? '',
formattedValue: formatHeatmapValue(
highlightedPoint.countVal,

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.

P2 Heatmap component exceeds size limit

The new series-axis hover and tooltip logic brings HeatmapPlot.tsx to 371 lines. The repository guide requires components to stay under 300 lines, so please extract the mode-specific plotting logic before merging.

Context Used: CLAUDE.md (source)

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Fix in Claude Code Fix in Conductor Fix in Cursor Fix in Codex


// Series-mode heatmaps have no external schema yet. Emitting them as
// distribution tiles would corrupt them on a GET -> PUT round-trip.
if (

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.

🟠 major — External API/MCP GET now drops series-mode heatmap tiles, so a GET → PUT round-trip deletes them

PUT replaces the tile list, and its TileInput doc in v2/dashboards.ts says only tiles whose id matches an existing tile are kept. So any client that reads a dashboard and writes it back silently deletes every series heatmap a user built in the UI. On update, merge back the existing tiles that GET skipped (series heatmaps, and PromQL by the same reasoning), or reject the PUT. The comment saying this avoids corruption is misleading, because the tile ends up deleted instead.

Nothing blocks merge automatically, but a maintainer will expect this fixed if it is a real defect in code this PR changes. If it is about surrounding code, reply and say so instead of patching. Do not widen the PR. How to respond

const SERIES_LABEL_MAX_LENGTH = 24;

/** Series-axis ticks, one centered on each row. */
function seriesRowSplits(rowCount: number): number[] {

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 — Series axis draws a tick label on every row, so labels overlap once rows are shorter than the font

seriesRowSplits returns one split per row with no thinning, and uPlot draws every split it is given. A 50-series heatmap (the cap) in a ~300px dashboard tile gives about 6px per row, and the 24-character labels pile on top of each other. Thin the splits based on the plot height and the axis font size, for example by keeping every k-th row so labels never overlap. The hover tooltip already shows the full name.

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

: seriesLabels != null
? {
kind: 'series',
name: seriesLabels[highlightedRow] ?? '',

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 — A blank group-by value shows as an empty 'Series:' in the cell tooltip, but as '(blank)' in the axis tooltip

useSeriesAxisHover (SeriesAxisTooltip.tsx) maps '' to '(blank)', but the cell tooltip passes seriesLabels[highlightedRow] through unchanged. Apply the same '(blank)' mapping here, ideally through one shared helper.

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

*/
export function isHeatmapCompatibleSource(
source: Pick<TSource, 'kind'>,
mode: HeatmapMode = 'distribution',

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 — New mode parameter on isHeatmapCompatibleSource is never passed by any caller

The only caller is getHeatmapTilesWithIncompatibleSources in api/.../v2/utils/dashboards.ts, and it calls with the source alone. The app uses getHeatmapSourceKinds directly. Drop the parameter until the external API supports series mode, or pass the tile's mode at that call site.

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

@kodiakhq
kodiakhq Bot merged commit 6873416 into main Oct 6, 2026
31 checks passed

This branch was successfully deployed

2 active deployments
Preview – hyperdx-oss — 5b1645f0 Deployed Oct 6, 2026 by vercel[bot]
Preview – hyperdx-storybook — 5b1645f0 Deployed Oct 6, 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.

2 participants