Skip to content

feat: Support series-mode heatmap in API and MCP - #3298

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

kodiakhq[bot] merged 2 commits into
mainfrom
drew/heatmap-series-5

Conversation

@pulpdrew

@pulpdrew pulpdrew commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds support for series-mode heatmaps to the dashboards external api and MCP.

Screenshots or video

Screenshot 2026-10-06 at 8 36 15 AM Screenshot 2026-10-06 at 8 36 22 AM Screenshot 2026-10-06 at 8 43 53 AM

How to test locally

  • Connect your agent to MCP
  • Ask it to create some heatmaps, confirm it can do it accurately
  • use the external API to CRUD dashboards with heatmaps

References

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

@changeset-bot

changeset-bot Bot commented Oct 5, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 0dece9f

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 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 5:36pm UTC
hyperdx-storybook Ready Ready Preview Oct 6, 2026 5:36pm UTC

Request Review

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

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

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

Findings outside the changed lines

  • 🟠 packages/api/src/mcp/prompts/dashboards/content.ts:993 — Other MCP prompt sections still say heatmaps are Trace-only, have no aggFn/alias, and have no groupBy → The per-tile constraints still say heatmaps are "Trace sources only (no Log/Metric/Session). No groupBy. No aggFn or alias on the select item". Gotcha 11 (~L1526-1529) still says "Heatmap is currently restricted to Trace sources", and the macro section (~L1229/1233) still lists heatmap as having a tile-level where. All of these contradict the new series-mode line at L65, so an agent reading the guide will either avoid series heatmaps or strip their aggFn/groupBy. Scope these statements to distribution heatmaps and add a series-heatmap line: one select item with aggFn, optional groupBy, where on the select item, and a Trace/Log/Metric source.
1 minor
  • 🔵 packages/api/src/mcp/tools/dashboards/schemas.ts:259 — Shared select-item alias description tells agents heatmap items need no alias, but series heatmaps now use this schema → mcpHeatmapSeriesTileSchema.select uses mcpTileSelectItemSchema, and that schema's alias description says "Heatmap select items are the only exception (no alias needed)". Prompt rule 2 was narrowed to distribution heatmaps, but this description was not. Change it to "Distribution heatmap select items are the only exception", or drop the sentence, since mcpHeatmapSelectItemSchema has no alias field at all.

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

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 5/5

[Critical risk] Adds new heatmap mode to the public API contract.

The PR appears safe to merge based on the changes reviewed.

Summary

The PR adds series-mode heatmaps to external dashboard CRUD and MCP dashboard tools.

  • Adds mode-specific schemas, source validation, and OpenAPI descriptions.
  • Returns series heatmaps through the external API and supplies time granularity for MCP tile queries.
  • Adds save, patch, query, and round-trip coverage.
Diagram
%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Client[External API or MCP client] --> Schema[Mode-specific tile schema]
  Schema --> Validate[Source compatibility check]
  Validate --> Saved[Saved dashboard tile]
  Saved --> Read[External read-back]
  Saved --> Query[MCP tile query]
  Query --> Buckets[Time-bucketed series result]
Loading

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

@github-actions

github-actions Bot commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

Deep Review

✅ No critical issues found.

This PR cleanly extends heatmap support to a second mode across the external API, OpenAPI spec, and MCP surface. The core risk areas verified out well: the hand-rolled getExternalBuilderTileConfigSchema router correctly discriminates series vs distribution (and rejects unknown/null modes with a 400), the external↔internal round-trip preserves the legacy-vs-explicit distribution distinction, the per-mode source-kind gate re-validates on mode change, and the MCP query path now injects time granularity for series heatmaps (resolving the prior P1 review comment). No data-loss, auth, or injection risks were introduced.

🟡 P2 -- recommended

  • packages/api/src/routers/external-api/v2/utils/dashboards.ts:488 -- groupBy is optional on series heatmaps and the conversion handles the omitted case (stringValueOrDefault(config.groupBy, undefined)), but every new test supplies a groupBy, so the no-groupBy round-trip and query path is unverified.
    • Fix: Add a REST save→get round-trip and an MCP clickstack_query_tile case for a series heatmap with groupBy omitted, asserting the config survives and the query returns time-bucketed rows.
    • testing
🔵 P3 nitpicks (7)
  • packages/api/src/routers/external-api/v2/utils/dashboards.ts:493 -- { heatmapMode: 'distribution' as const } uses an as assertion, which agent_docs/code_style.md:8 asks contributors to avoid; this is a const assertion (not a type-bypass cast) and is defensible, but was raised in prior review and remains unaddressed.
    • Fix: Replace with an explicit annotation such as const heatmapField: { heatmapMode?: 'distribution' } = config.heatmap ? { heatmapMode: 'distribution' } : {} if conforming to the rule is preferred.
    • previous-comments, project-standards, kieran-typescript
  • packages/api/src/routers/external-api/v2/utils/dashboards.ts:1130 -- (mode === 'series' ? series : distribution) and the two-branch error reporting treat every non-series mode as distribution, so a future third HeatmapMode would be validated and error-messaged as distribution silently; the Record<HeatmapMode, string[]> return is only a partial compile-time guard.
    • Fix: Use an exhaustive switch over mode with a never default so a new mode forces every branch to update.
    • kieran-typescript
  • packages/api/src/routers/external-api/v2/utils/dashboards.ts:492 -- A distribution tile emits heatmapMode: 'distribution' on GET only when the internal config has a heatmap object, so a legacy distribution tile and a newly-saved one return different JSON for the same logical tile.
    • Fix: Decide on one GET shape for distribution (always emit, or never emit) and document it; the field is optional in the oneOf so either choice stays non-breaking.
    • api-contract, maintainability
  • packages/api/openapi.json:127 -- The HeatmapChartConfig oneOf has no discriminator; the two branches are unambiguous to a validator via heatmapMode and select-item shape, but code generators may emit an ambiguous union.
    • Fix: Document the disambiguation rule in the schema description, or make heatmapMode required-with-default in both branches if a discriminator is desired.
    • api-contract
  • packages/api/src/mcp/tools/dashboards/schemas.ts:1161 -- The series schema must precede the distribution schema in mcpTileSchema/mcpPatchTileSchema, but the rationale lives only in a test comment, and that test does not actually exercise ordering (a heatmapMode:'series' config already fails the distribution literal, so it passes regardless of order).
    • Fix: Add a comment at both union sites explaining the ordering constraint (or why the literal makes the schemas unambiguous), and tighten or correct the test comment.
    • maintainability, testing
  • packages/api/src/mcp/__tests__/dashboards/saveDashboard.int.test.ts:349 -- The REST surface has a 'bogus' invalid-mode rejection test, but the MCP surface has no negative case for an invalid/null/empty heatmapMode.
    • Fix: Add an MCP save case with heatmapMode: 'bogus' (and null/'') asserting isError is truthy.
    • testing
  • packages/api/src/routers/external-api/v2/utils/dashboards.ts:1535 -- The per-mode incompatible-source grouping and the two sequential error returns in validateDashboardTiles are each tested only one mode at a time, never with an incompatible distribution tile and an incompatible series tile on the same source in one request.
    • Fix: Add a case with both modes on incompatible sources in one POST/PUT, asserting error precedence and that the per-mode split is populated.
    • testing

Reviewers (10): correctness, adversarial, testing, maintainability, project-standards, api-contract, kieran-typescript, previous-comments, agent-native, learnings-researcher.

Note: the correctness, adversarial, and agent-native reviewers did not return before synthesis; their highest-stakes paths (schema routing, unknown-mode handling, round-trip fidelity, MCP parity) were independently verified against the code and corroborated by the TypeScript and API-contract reviewers.

Testing gaps:

  • Series heatmap with groupBy omitted — no round-trip or query coverage.
  • Distribution-mode heatmap query_tile — no coverage to guard the granularityOverride change against regression (pre-existing gap).
  • Invalid/null/empty heatmapMode rejection on the MCP surface — uncovered.
  • Combined distribution + series incompatible-source validation in one request — uncovered.
  • getExternalBuilderTileConfigSchema router predicate is exercised only end-to-end, never in isolation.

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

kodiakhq Bot pushed a commit that referenced this pull request Oct 6, 2026
## 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

<img width="1833" height="1199" alt="Screenshot 2026-10-05 at 9 24 48 AM" src="https://github.com/user-attachments/assets/1e969db7-104c-46e0-8a24-d9c406345df7" />


### How to test on Vercel preview

Create some series-mode heatmaps

### References



- Linear Issue: Closes HDX-5607
- Related PRs: #3298
@pulpdrew
pulpdrew changed the base branch from drew/heatmap-series-4 to main October 6, 2026 11:58
@pulpdrew
pulpdrew force-pushed the drew/heatmap-series-5 branch from f1179ac to 8e6f2ff Compare October 6, 2026 11:58
@github-actions github-actions Bot added the review/tier-4 Critical — deep review + domain expert sign-off label Oct 6, 2026
@github-actions

github-actions Bot commented Oct 6, 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/utils/dashboards.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: 7
  • Production lines changed: 377 (+ 462 in test files, excluded from tier calculation)
  • Critical-path lines changed: 188
  • Branch: drew/heatmap-series-5
  • 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 6, 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.

@github-actions

github-actions Bot commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

E2E Test Results

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

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

Tests ran across 4 shards in parallel.

View full report →

@pulpdrew
pulpdrew force-pushed the drew/heatmap-series-5 branch from 8e6f2ff to e9f326d Compare October 6, 2026 12:24
Comment thread .changeset/proud-walls-argue.md Resolved
@pulpdrew
pulpdrew requested review from a team and removed request for a team October 6, 2026 13:43

@brandon-pereira brandon-pereira left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@kodiakhq
kodiakhq Bot merged commit 837c683 into main Oct 6, 2026
29 checks passed
@kodiakhq
kodiakhq Bot deleted the drew/heatmap-series-5 branch October 6, 2026 17:43

This branch was successfully deployed

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