docs(clickstack): document heatmap dashboard tile#6151
Merged
alex-fedotyev merged 3 commits intomainfrom May 5, 2026
Merged
Conversation
Add a Heatmap step to the Custom Dashboards walkthrough covering: - when to use a heatmap vs a Line chart (distribution shape over time) - that the data source dropdown is restricted to Traces sources (logs, metrics, and session sources are filtered out, since heatmaps need the source's Duration Expression for span duration) - the pre-filled Value (`(Duration)/1e6`) and Count (`count()`) once a source is selected - using `Where` and the time range to scope the heatmap to a service or set of operations the user wants to observe, with wider ranges making bimodal latency patterns easier to spot - the Display Settings drawer (Scale / Value / Count), with a cross-link to the Event Deltas page where the full settings table already lives - the two-query model (bounds + bucket) visible in the editor SQL preview - a Drill down to Event Deltas subsection: clicking a cell on a rendered tile reveals a "View in Event Deltas" action that opens the Event Deltas view with the tile's data source, Where clause, and time range carried over Cross-link the existing Event Deltas "Customize the heatmap" section to the new dashboard tile flow so users discovering the feature in either place find the other. Screenshots are captured in dark theme to match neighbouring sections, with `ServiceName:"payment"` over 24h to surface the bimodal duration distribution that makes a heatmap worth using. Closes #6146 Refs hyperdxio/hyperdx#2107
|
The latest updates on your projects. Learn more about Vercel for GitHub.
4 Skipped Deployments
|
Use the exact button label `Run` (the button shows a play icon but its visible label is `Run`). Rename the second query in the tip block to `heatmap query` to match the label the editor uses in the Generated SQL accordion (`1. Bounds query`, `2. Heatmap query`).
Blargian
approved these changes
May 5, 2026
Member
Blargian
left a comment
Blargian
left a comment
There was a problem hiding this comment.
LGTM. I left two small suggestions to break up the text into steps for easier readability.
|
|
||
| Heatmap tiles plot the count of events falling into each (time, value) bucket as a colored grid. Use a heatmap when you want to see the **shape** of a distribution over time, not just the average or a single percentile. A latency heatmap reveals bimodal duration patterns, slow-tail clusters, or sudden spreads that a Line chart would average away. | ||
|
|
||
| Select `Add New Tile`, then choose the `Heatmap` visualization type from the top menu. The data source dropdown only shows sources whose [source type is `Traces`](/use-cases/observability/clickstack/config#traces); logs, metrics, and session sources are filtered out, since heatmaps need a span duration column that only traces sources provide. Pick any of your traces sources by name; the name itself is arbitrary, only the type matters. |
Member
There was a problem hiding this comment.
Suggested change
| Select `Add New Tile`, then choose the `Heatmap` visualization type from the top menu. The data source dropdown only shows sources whose [source type is `Traces`](/use-cases/observability/clickstack/config#traces); logs, metrics, and session sources are filtered out, since heatmaps need a span duration column that only traces sources provide. Pick any of your traces sources by name; the name itself is arbitrary, only the type matters. | |
| To add a heatmap tile: | |
| 1. Select `Add New Tile` | |
| 2. Choose the `Heatmap` visualization type from the top menu. The data source dropdown only shows sources that have a source type of `Traces`](/use-cases/observability/clickstack/config#traces). Logs, metrics, and session sources are filtered out, since heatmaps need a span duration column that only traces sources provide. | |
| 3. Pick any of your traces sources by name. The name itself is arbitrary, only the type matters. |
| - **Value**: the source's `Duration Expression`, scaled to the current display unit (for example `(Duration)/1e6` to convert each event's span duration from nanoseconds to milliseconds) | ||
| - **Count**: `count()` | ||
|
|
||
| Set a chart name, and use `Where` to scope the heatmap to a specific service or set of operations whose performance you want to observe. Adjust the time range to match the period of interest; wider ranges expose distribution shifts and bimodal latency patterns that shorter windows can hide. The example below shows a single service over a 24 hour window, with the fast and slow paths of its span duration clearly separated into two horizontal bands. To customize the heatmap further, click **Display Settings** to open a drawer for the **Scale** (Log or Linear), **Value**, and **Count** expression. The full list of options is documented in [Customize the heatmap](/use-cases/observability/clickstack/event_deltas#customize) on the Event Deltas page; the same drawer is reused. |
Member
There was a problem hiding this comment.
Suggested change
| Set a chart name, and use `Where` to scope the heatmap to a specific service or set of operations whose performance you want to observe. Adjust the time range to match the period of interest; wider ranges expose distribution shifts and bimodal latency patterns that shorter windows can hide. The example below shows a single service over a 24 hour window, with the fast and slow paths of its span duration clearly separated into two horizontal bands. To customize the heatmap further, click **Display Settings** to open a drawer for the **Scale** (Log or Linear), **Value**, and **Count** expression. The full list of options is documented in [Customize the heatmap](/use-cases/observability/clickstack/event_deltas#customize) on the Event Deltas page; the same drawer is reused. | |
| 4. Set a chart name, and use `Where` to scope the heatmap to a specific service or set of operations whose performance you want to observe. | |
| 5. Adjust the time range to match the period of interest. Wider ranges expose distribution shifts and bimodal latency patterns that shorter windows can hide. | |
| The example below shows a single service over a 24 hour window, with the fast and slow paths of its span duration clearly separated into two horizontal bands. | |
| To customize the heatmap further, click **Display Settings** to open a drawer for the **Scale** (Log or Linear), **Value**, and **Count** expression. The full list of options is documented in [Customize the heatmap](/use-cases/observability/clickstack/event_deltas#customize) on the Event Deltas page. The same drawer is reused. |
Applies Blargian's suggestions from the LGTM review: convert the prose paragraph describing Add New Tile, source selection, name, and time-range into a five-step numbered list. No content changes, just structure.
alex-fedotyev
commented
May 5, 2026
Contributor
Author
alex-fedotyev
left a comment
alex-fedotyev
left a comment
There was a problem hiding this comment.
Good call on the numbered steps. Applied in e5b39a7.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #6146.
Re-opening from an in-repo branch so Vercel preview deploys can authorize automatically. Replaces #6150.
Summary
Adds a Heatmap step to
dashboards/index.mdso the Custom Dashboards walkthrough covers the new visualization type alongside Line/Bar, and cross-links from the existing Event Deltas page so users discovering the feature in either place find the other.The Heatmap tile shipped to ClickStack/HyperDX in hyperdxio/hyperdx#2107.
What the new section covers
Traces. Logs, metrics, and session sources are filtered out, since heatmaps need the source'sDuration Expressionfor span duration. (MatchesallowedSourceKinds={[SourceKind.Trace]}inChartEditorControls.tsx.)Valueset to(Duration)/1e6,Countset tocount(), withnumberFormatfor proper Y-axis labels.Whereto scope the heatmap to a specific service or set of operations, and adjusting the time range to match the period of interest. Wider ranges expose distribution shifts that shorter windows hide.View in Event Deltasaction that opens the Event Deltas view with the tile's data source,Whereclause, and time range carried over.Use cases covered
Screenshots
Three screenshots, all dark theme to match neighbouring sections, captured at
play-clickstack.clickhouse.comagainst the demo traces dataset:heatmap-tile-editor.png: Heatmap tab selected in the chart editor withServiceName:"payment"filter and the bimodal preview, showing the Display Settings button.heatmap-tile-rendered.png: Saved tile on the dashboard over a 24h window with the fast and slow paths clearly separated.heatmap-tile-drilldown.png: cell click revealing theView in Event Deltasaction.Validation
Walked the flow end to end on
play-clickstack.clickhouse.com:ClickPy TracesandDemo Traceswhen Heatmap is selected; logs/metrics sources do not appear.Value=(Duration)/1e6,Count=count()populate on source selection.View in Event Deltasaction; selecting it lands on/search?source=...&where=ServiceName%3A%22payment%22&from=...&to=...&mode=deltawith the data source,Whereclause, and time range carried over, and the Event Deltas analysis mode panel selected.Local
yarn buildwould have flagged a broken link inherited from the prior draft (event-deltas#customizevsevent_deltas#customize); fixed in this iteration so DocsCheck passes.