Skip to content

feat: add distribution heatmaps to the MCP server, hdx and the Claude plugin - #3401

Open
jordan-simonovski wants to merge 3 commits into
jordansimonovski/claude-charts-pluginfrom
jordansimonovski/distribution-heatmaps
Open

jordan-simonovski wants to merge 3 commits into
jordansimonovski/claude-charts-pluginfrom
jordansimonovski/distribution-heatmaps

Conversation

@jordan-simonovski

@jordan-simonovski jordan-simonovski commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Agents and hdx can now see how a value such as span latency is distributed over time, the data behind a latency heatmap. Until now the bucketing for distribution heatmaps ran only in the browser, so the MCP server and hdx had no way to produce one.

  • New MCP tool clickstack_heatmap: counts per time bucket and value range for a numeric expression on a trace source, as compact JSON with the bucket bounds and a note on how to read them.
  • clickstack_query_tile answers saved distribution heatmap tiles with the same grid, at auto granularity (heatmap tiles in the external dashboard format don't carry one). clickstack_query_tiles reports whether a heatmap tile has data.
  • hdx chart --dashboard ... --tile ... draws distribution heatmap tiles as shaded terminal cells, and --json returns them in the same shape as the MCP result. Series-mode heatmap tiles still show a placeholder.
  • The Claude plugin draws clickstack_heatmap results and heatmap query_tile results.

Key decisions

  • Move the web's queries rather than reimplement them. The bounds query, the widthBucket bucket query and gridFromBucketRows move from packages/app into common-utils (core/heatmap.ts, core/heatmapQuery.ts), and isAggregateFunction moves to core/utils.ts. The app keeps re-exports, so its behaviour and tests are unchanged. A new queryDistributionHeatmap (core/distributionHeatmap.ts) runs both queries for any client with queryChartConfig, which the API and CLI clients both have.
  • Size the MCP result for an agent. About 48 time buckets by 20 value buckets, sent as counts[t][r] with valueEdges, rather than one row per cell. The edges are the true widthBucket bounds, not the web's display edges, which sit half a bucket off. One HeatmapResultSchema in common-utils defines this shape for the MCP server, hdx --json and the Claude plugin.
  • Validate granularity. ClickHouse accepts INTERVAL 1 week, but the JS bucket generator only steps by second, minute, hour or day and would loop forever on anything else. The tool's schema now rejects other units, a saved tile's unsupported or too-fine granularity is replaced (with a hint saying so), and timeBucketByGranularity returns no buckets for a step it can't take.

Impact

  • New MCP tool in the server's tool list and in MCP.md.
  • clickstack_query_tile on a distribution heatmap tile now returns { heatmap, hints } instead of running the tile through the generic chart query. Its results for other tiles are unchanged.
  • Lint budgets: common-utils goes from 80 to 83 warnings because three existing warnings moved with the code; the app's budget drops from 568 to 567.

How to reproduce

Starting point: yarn dev, a trace source with data, and a dashboard with a distribution heatmap tile on Duration.

  1. Call clickstack_heatmap with that source and valueExpression: "Duration". The result has times, valueEdges and counts, plus a numberFormat marking the values as durations.
  2. Call clickstack_query_tile on the heatmap tile. It returns the same grid.
  3. yarn cli:dev chart --dashboard <name> --tile <heatmap tile> draws the heatmap in the terminal.
  4. Call clickstack_heatmap with granularity: "1 week"; it is rejected instead of hanging the API.

How to test on Vercel preview

N/A, non-UI change. The web heatmap only gains re-exports.

References

Implementation detail
  • runConfigTile gets a distribution-heatmap branch next to the event-patterns one. It refuses non-trace sources, matching the web's rule, and maps ClickHouse errors through clickHouseErrorResult like the other builder tools.
  • resolveDistributionGranularity keeps a requested granularity when it is a supported unit and makes at most four times the target bucket count, otherwise it falls back to auto granularity with a note.
  • termchart's renderHeatmapChart trims empty value rows, merges or stretches buckets to fit the terminal, and shades on a log scale of counts so one dense bucket doesn't wash out the rest.
  • Tests: common-utils unit tests for the runner, granularity resolution, bucket edges and the zero-step guard; API integration tests for the tool (bimodal latency data, unsupported and too-fine granularity, a non-trace source, a saved tile through query_tile); CLI tests for heatmap tile fetch and render; plugin unit and engine tests for heatmap results. otel_traces isn't truncated between integration tests, so each test filters to its own spans.

@changeset-bot

changeset-bot Bot commented Oct 19, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 29ff90d

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

This PR includes changesets to release 6 packages
Name Type
@hyperdx/claude-plugin Minor
@hyperdx/cli Patch
@hyperdx/api Patch
@hyperdx/common-utils 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 19, 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 20, 2026 10:39am UTC
hyperdx-storybook Ready Ready Preview Oct 20, 2026 10:39am UTC

Request Review

@github-actions

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

Comment thread packages/cli/src/shared/tileRender.ts Resolved
Comment thread packages/cli/src/shared/chartData.ts Resolved
Comment thread packages/cli/src/shared/tileQuery.ts Resolved
@github-actions

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

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

4 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 19, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 4/5

[Medium impact] The changes reach a bounded trace-heatmap workflow across MCP, the CLI, and Claude's chart plugin.

Fix custom interval alignment before merging so populated heatmaps do not appear empty.

Fix All in Claude CodeFindings

  1. P1 Custom intervals hide heatmap data ▶

Summary

Adds distribution heatmaps to MCP, saved dashboard queries, hdx, and the Claude plugin.

  • MCP callers can get value distributions over time from trace data.
  • hdx draws distribution heatmap tiles as shaded terminal charts.
  • Claude's chart plugin draws heatmaps returned by direct and saved-tile calls.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  MCP[MCP heatmap or saved tile] --> Runner[Shared heatmap runner]
  CLI[hdx saved tile] --> Runner
  Runner --> Bounds[Query value bounds]
  Bounds --> Buckets[Query bucket counts]
  Buckets --> Grid[Build heatmap grid]
  Grid --> JSON[Compact JSON]
  Grid --> Terminal[Terminal chart]
  JSON --> Plugin[Claude plugin chart]
Loading

Reviews (3) · Last reviewed commit: "fix(mcp): draw saved heatmap tiles at th..." · Reviewed by Greptile

Comment thread packages/cli/src/shared/tileQuery.ts Resolved
Comment thread packages/cli/src/shared/tileQuery.ts Resolved
@github-actions

github-actions Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Deep Review

✅ No critical issues found.

The prior P1 review threads on this PR appear resolved at the current head: saved heatmap tiles now thread their stored granularity through (savedTileGranularity → runConfigTile savedGranularity → granularity ?? savedGranularity in packages/api/src/mcp/tools/query/helpers.ts:637), hdx chart --json carries the heatmap grid, valueEdges are emitted unrounded, the CLI axis uses heatmapNumberFormat, and the plugin only evicts a chart when the result is chartable. The remaining observations are recommendations, not blockers.

🟡 P2 — recommended

  • packages/common-utils/src/core/heatmap.ts:240 — gridFromBucketRows walks the result with a single forward dataIndex and an outer loop over time buckets then value buckets, so it assumes rows arrive ordered timestamp-major then x_bucket-ascending, but the bucket query sets orderBy: [{ valueExpression: 'x_bucket', ordering: 'ASC' }] only (packages/common-utils/src/core/heatmapQuery.ts:205 and :222), leaving the inter-timestamp order unspecified; if ClickHouse returns rows grouped by x_bucket across timestamps, cells are matched against the wrong (ts, bucket) pair and silently zeroed.
    • Fix: Add the time-bucket column ahead of x_bucket in the bucket query's orderBy, and cover it with a test using more than one time bucket of data.

🟡 P2 — testing

  • packages/common-utils/src/core/heatmap.ts:208 — The distributed-table dedup branch (// Skip duplicate buckets (from unmerged distributed table results)) and the ordering assumption above have no direct unit test exercising duplicate or out-of-order rows, so a regression in grid assembly would not be caught.
    • Fix: Add a gridFromBucketRows test feeding duplicate and multi-timestamp rows and asserting the resulting cells.
🔵 P3 nitpicks (2)
  • packages/common-utils/src/core/heatmap.ts:118 — heatmapRowEdges dereferences bucketEdges[0]! and bucketEdges.at(-1)! with non-null assertions; called with an empty or single-element array it yields NaN/undefined row edges rather than a clear error.
    • Fix: Guard for bucketEdges.length < 2 or document the nBuckets + 1 precondition at the call sites.
  • packages/common-utils/src/core/heatmap.ts:249 — Number.parseInt(row['count'], 10) produces NaN if a row ever carries a null/absent count, which would serialize into counts as null for an agent; a || 0 fallback makes the empty-cell contract explicit.
    • Fix: Default a non-numeric parsed count to 0.

Reviewers (2): ce-learnings-researcher, orchestrator direct analysis.

Coverage note: The multi-agent fan-out (correctness, testing, maintainability, project-standards, agent-native, kieran-typescript, performance, reliability, adversarial, api-contract, security, previous-comments) was dispatched but had not returned results when output was required, so the findings above reflect the orchestrator's own verified reading of the diff plus the learnings search (which found no prior docs/solutions/ entries relevant to ClickHouse bucketing, MCP tool design, or terminal rendering). Not independently re-verified by the persona reviewers.

Testing gaps: grid assembly ordering and distributed-dedup paths; the resolveDistributionGranularity unsupported/too-fine fallbacks and the max <= effectiveMin "not enough distinct values" path should each have explicit assertions if not already present in distributionHeatmap.test.ts.

Note on SQL interpolation: valueExpression/countExpression are string-interpolated into ClickHouse SQL in heatmapQuery.ts, but this mirrors the existing builder chart-config design (numeric bounds go through Number.parseFloat, and readonly=2 + max_execution_time remain enforced on this path), so it is pre-existing design rather than a new injection vector.

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

@github-actions

github-actions Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

E2E Test Results

✅ All tests passed • 440 passed • 1 skipped • 1403s

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

Tests ran across 4 shards in parallel.

View full report →

@vercel
vercel Bot temporarily deployed to Preview – hyperdx-storybook October 19, 2026 08:14 Inactive
@jordan-simonovski

Copy link
Copy Markdown
Contributor Author

The app's own timeBucketByGranularity copy didn't get the zero-step guard and still loops forever

Not changed here: that copy is a separate web code path this PR doesn't use, and guarding it means changing other call sites. The web only offers granularities in supported units, so it can't receive a week-long step from this change. It's worth folding the app's copy into the common-utils one in a follow-up.

) {
return {
status: 'unsupported',
message: `Distribution heatmaps need a trace source; "${source.name}" is a ${source.kind} source.`,

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 — hdx drops granularityNote, so a replaced --granularity changes the chart without telling the user

queryDistributionHeatmap returns granularityNote when it swaps out a requested granularity. The MCP server shows that note as a hint, but fetchTileData discards it. So hdx chart --granularity "1 second" over 1h (3600 buckets, over the 4×maxTimeBuckets ≈ 320 cap) quietly draws at auto granularity. Pass the note through on the heatmap result and print it as a dim callout in renderTileContent (and in --json).

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

}

/** A trace duration column formats as a duration unless the tile says otherwise. */
export function heatmapNumberFormat(

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 — Second heatmapNumberFormat repeats the trace-duration format rule with different precedence than the CLI's

This repeats getTraceDurationNumberFormat (packages/app/src/source.ts:572, ported in packages/cli/src/shared/formatNumber.ts:349). The PR also adds a same-named heatmapNumberFormat in packages/cli/src/shared/formatNumber.ts. The CLI version honours select[0].numberFormat; this one only reads config.numberFormat. So hdx --json and clickstack_heatmap, which are documented as the same shape, can return different numberFormat for the same tile. Move one implementation into common-utils (e.g. next to toHeatmapResult) and call it from both packages.

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

return chalkColor(SHADE_COLORS[level])(SHADES[level]);
};

const labels = new Map([

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 — Heatmap y-axis labels show made-up edges (negative on linear scale) and lose the top label when the plot is 2 rows tall

Two problems with the axis labels:

  • Underflow/overflow rows: their outer edges come from heatmapRowEdges padding, not from data. The overflow row always holds the max sample (widthBucket puts x >= max there), so the top label is one bucket above the true max. On linear scale, values below the 0.001 quantile fill the underflow row, so the bottom label is min - step, e.g. "-25ms" for Duration. Fix: when the first or last visible row is an under/overflow row, label it with its inner bound and a </≥ prefix.
  • plotHeight 2: Math.floor(plotHeight / 2) === plotHeight - 1, so the middle-label Map entry overwrites the top label. Fix: skip the middle label when its key collides with the top or bottom row.

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

…ugin

Agents can now see how a value such as span latency is distributed over
time. The new clickstack_heatmap MCP tool returns counts per time bucket and
value range, and clickstack_query_tile answers saved distribution heatmap
tiles instead of failing. hdx draws distribution heatmap tiles, and the
Claude plugin draws both results.

The bounds and widthBucket queries the web app ran in the browser move to
common-utils, so the web, API and CLI share one copy. Caller-supplied
granularity is validated, and a size that would flood the grid is coarsened
with a hint, so a value like "1 week" can no longer stall bucket generation.
Address review feedback on #3401:

- hdx labels heatmap rows with the bucket bounds widthBucket counted (the
  plugin's edge helper moves to common-utils), formats saved Duration
  tiles as durations, refuses non-trace sources, keeps a saved tile's
  granularity, and includes the heatmap in --json output.
- One HeatmapResultSchema and builder in common-utils shape the MCP
  result, hdx --json and what the plugin validates; value edges keep
  full precision.
- Drop the query_tile granularity fallback, which external heatmap tiles
  never carry.
- The plugin caches only results it can draw, so query_tile calls on
  other tiles no longer evict charts.
query_tile and query_tiles read tiles in the external format, which has no
granularity, so saved distribution heatmaps fell back to auto buckets. Also
declare the heatmap tool's annotations with READ_ONLY_TOOL, which main now requires.
@jordan-simonovski
jordan-simonovski force-pushed the jordansimonovski/distribution-heatmaps branch from 234add7 to 29ff90d Compare October 20, 2026 10:32
@github-actions github-actions Bot added the review/tier-4 Critical — deep review + domain expert sign-off label Oct 20, 2026
@github-actions

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:

  • Large diff: 1859 production lines changed (threshold: 1000)
  • 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: 31
  • Production lines changed: 1859 (+ 849 in test files, excluded from tier calculation)
  • Branch: jordansimonovski/distribution-heatmaps
  • Author: jordan-simonovski

To override this classification, remove the review/tier-4 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

}

/** A trace duration column formats as a duration unless the tile says otherwise. */
export function heatmapNumberFormat(

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 — Third copy of the trace-duration number format; it also disagrees with the CLI's twin, so MCP and hdx --json can return different numberFormat for the same tile

heatmapNumberFormat here re-implements getTraceDurationNumberFormat (already ported twice: packages/app/src/source.ts and packages/cli/src/shared/formatNumber.ts:349). This PR also adds a second heatmapNumberFormat in packages/cli/src/shared/formatNumber.ts:584, and the two behave differently. The CLI one goes through resolveChartNumberFormats → getFirstSeriesNumberFormat, which honours select[0].numberFormat. The API one only checks config.numberFormat, then the duration column. So a tile whose format is set on its select item gets a different numberFormat from MCP than from hdx --json, even though the PR says both use one shape. Fix: move one heatmapNumberFormat(config, source) (config/select format first, then the trace-duration fallback) into common-utils next to toHeatmapResult, and call it from both the API and the CLI.

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

function readingHint(scale: HeatmapScaleType) {
return (
'valueEdges are in the units of valueExpression (when numberFormat.factor is ' +
'present, value x factor is seconds). counts[t] has one entry per range: ' +

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 — Reading hint tells the agent value x factor is seconds for any numberFormat, not just durations

The hint always says "when numberFormat.factor is present, value x factor is seconds". But numberFormat comes from the saved tile verbatim (config.numberFormat), so a tile formatted as { output: 'byte', factor: 1 } or { output: 'number', factor: 0.001 } gets told its values are seconds. Pass the resolved numberFormat into readingHint and only add the seconds sentence when numberFormat?.output === 'duration'.

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

note: `Granularity "${granularity}" is not supported (use "<n> second|minute|hour|day"); used "${auto}".`,
};
}
const seconds = convertGranularityToSeconds(granularity as SQLInterval);

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 — granularity as SQLInterval casts after the value was already validated by safeParse

Keep the parse result (const parsed = SQLIntervalSchema.safeParse(granularity)) and use parsed.data in both places (lines 191 and 200) instead of casting. The base conventions say to avoid as casts. Note that SQLIntervalSchema is a plain z.string().regex(...), so to get a typed value back you may need to brand it or narrow it with a type guard.

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

displayType: DisplayType.Heatmap,
dateRange: [start, end],
numberFormat: heatmap.numberFormat,
} as unknown as ChartConfigWithDateRange,

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 — Heatmap queriedConfig is built with as unknown as ChartConfigWithDateRange

The double cast hides the fact that this object has none of the required builder fields (select, from, timestampValueExpression, connection). It only type-checks because the CLI renderer happens to read just displayType, dateRange and numberFormat. Narrow the heatmap arm of TileQueryResult (packages/cli/src/shared/tileQuery.ts) to take a Pick<ChartConfigWithDateRange, 'displayType' | 'dateRange' | 'numberFormat'>-style config, and build that here without a cast. The base conventions say to avoid as casts.

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

Comment on lines +191 to +200
const seconds = convertGranularityToSeconds(granularity as SQLInterval);
const buckets =
(dateRange[1].getTime() - dateRange[0].getTime()) / 1000 / seconds;
if (!(seconds > 0) || buckets > targetBuckets * 4) {
return {
granularity: auto,
note: `Granularity "${granularity}" would make ${Math.round(buckets)} time buckets; used "${auto}".`,
};
}
return { granularity: granularity as SQLInterval };

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.

P1 Custom intervals hide heatmap data

resolveDistributionGranularity accepts intervals that JavaScript cannot align with ClickHouse. For example, request 90 second starting at 2026-10-13T00:01:10Z. JavaScript starts its buckets at 00:01:00, while ClickHouse starts the matching bucket at 00:00:00.

gridFromBucketRows requires an exact timestamp match and never advances past that unmatched row. A populated query therefore returns an all-zero heatmap. Align the generated buckets with ClickHouse, or reject intervals the generator cannot reproduce.

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

This branch was successfully deployed

2 active deployments
Preview – hyperdx-oss — 29ff90d6 Deployed Oct 20, 2026 by vercel[bot]
Preview – hyperdx-storybook — 29ff90d6 Deployed Oct 20, 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-4 Critical — deep review + domain expert sign-off

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant