Repository navigation
feat: add distribution heatmaps to the MCP server, hdx and the Claude plugin - #3401
jordan-simonovski wants to merge 3 commits into
Conversation
🦋 Changeset detectedLatest commit: 29ff90d The changes in this PR will be included in the next version bump. This PR includes changesets to release 6 packages
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 |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Duplicate code analysisNo new duplicate code introduced by this PR. jscpd compared this branch against |
PR Review
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. |
[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.
|
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 🟡 P2 — recommended
🟡 P2 — testing
🔵 P3 nitpicks (2)
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 Testing gaps: grid assembly ordering and distributed-dedup paths; the Note on SQL interpolation: 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 |
E2E Test Results✅ All tests passed • 440 passed • 1 skipped • 1403s
Tests ran across 4 shards in parallel. |
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.`, |
There was a problem hiding this comment.
🔵 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( |
There was a problem hiding this comment.
🔵 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([ |
There was a problem hiding this comment.
🔵 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
heatmapRowEdgespadding, not from data. The overflow row always holds the max sample (widthBucket putsx >= maxthere), 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 ismin - 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.
234add7 to
29ff90d
Compare
🔴 Tier 4 — CriticalTouches 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:
Review process: Deep review from a domain expert. Synchronous walkthrough may be required. Stats
|
| } | ||
|
|
||
| /** A trace duration column formats as a duration unless the tile says otherwise. */ | ||
| export function heatmapNumberFormat( |
There was a problem hiding this comment.
🔵 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: ' + |
There was a problem hiding this comment.
🔵 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); |
There was a problem hiding this comment.
🔵 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, |
There was a problem hiding this comment.
🔵 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
| 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 }; |
There was a problem hiding this comment.
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.
Summary
Agents and
hdxcan 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 andhdxhad no way to produce one.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_tileanswers saved distribution heatmap tiles with the same grid, at auto granularity (heatmap tiles in the external dashboard format don't carry one).clickstack_query_tilesreports whether a heatmap tile has data.hdx chart --dashboard ... --tile ...draws distribution heatmap tiles as shaded terminal cells, and--jsonreturns them in the same shape as the MCP result. Series-mode heatmap tiles still show a placeholder.clickstack_heatmapresults and heatmapquery_tileresults.Key decisions
widthBucketbucket query andgridFromBucketRowsmove frompackages/appintocommon-utils(core/heatmap.ts,core/heatmapQuery.ts), andisAggregateFunctionmoves tocore/utils.ts. The app keeps re-exports, so its behaviour and tests are unchanged. A newqueryDistributionHeatmap(core/distributionHeatmap.ts) runs both queries for any client withqueryChartConfig, which the API and CLI clients both have.counts[t][r]withvalueEdges, rather than one row per cell. The edges are the truewidthBucketbounds, not the web's display edges, which sit half a bucket off. OneHeatmapResultSchemain common-utils defines this shape for the MCP server,hdx --jsonand the Claude plugin.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), andtimeBucketByGranularityreturns no buckets for a step it can't take.Impact
MCP.md.clickstack_query_tileon 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.How to reproduce
Starting point:
yarn dev, a trace source with data, and a dashboard with a distribution heatmap tile onDuration.clickstack_heatmapwith that source andvalueExpression: "Duration". The result hastimes,valueEdgesandcounts, plus anumberFormatmarking the values as durations.clickstack_query_tileon the heatmap tile. It returns the same grid.yarn cli:dev chart --dashboard <name> --tile <heatmap tile>draws the heatmap in the terminal.clickstack_heatmapwithgranularity: "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
runConfigTilegets a distribution-heatmap branch next to the event-patterns one. It refuses non-trace sources, matching the web's rule, and maps ClickHouse errors throughclickHouseErrorResultlike the other builder tools.resolveDistributionGranularitykeeps 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.renderHeatmapCharttrims 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.query_tile); CLI tests for heatmap tile fetch and render; plugin unit and engine tests for heatmap results.otel_tracesisn't truncated between integration tests, so each test filters to its own spans.