Skip to content

docs(clickstack): document heatmap dashboard tile#6150

Closed
alex-fedotyev wants to merge 1 commit intoClickHouse:mainfrom
alex-fedotyev:docs/heatmap-dashboard-tile
Closed

docs(clickstack): document heatmap dashboard tile#6150
alex-fedotyev wants to merge 1 commit intoClickHouse:mainfrom
alex-fedotyev:docs/heatmap-dashboard-tile

Conversation

@alex-fedotyev
Copy link
Copy Markdown
Contributor

Closes #6146.

Summary

Adds a Heatmap step to dashboards/index.md so 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

  • When to use a heatmap vs a Line chart: see the shape of a distribution over time, not just the average or a single percentile. Reveals bimodal duration patterns, slow-tail clusters, sudden spreads.
  • Source-type constraint: the data source dropdown only shows sources whose source type is Traces. Logs, metrics, and session sources are filtered out, since heatmaps need the source's Duration Expression for span duration. (Matches allowedSourceKinds={[SourceKind.Trace]} in ChartEditorControls.tsx.)
  • Pre-fill behaviour once a source is selected: Value set to (Duration)/1e6, Count set to count(), with numberFormat for proper Y-axis labels.
  • Using Where to 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.
  • The Display Settings drawer (Scale / Value / Count expression). Cross-links to the existing settings table on the Event Deltas page rather than duplicating it.
  • The two-query model (bounds + bucket) visible under Generated SQL.
  • Drill down to Event Deltas: 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.

Use cases covered

  • Building a service-level latency dashboard tile and recognizing a bimodal distribution.
  • Pivoting from a tile cell into Event Deltas to investigate which spans drive a slow tail.
  • Configuring scale / value / count when the defaults are not enough.

Screenshots

Three screenshots, all dark theme to match neighbouring sections, captured at play-clickstack.clickhouse.com against the demo traces dataset:

  • heatmap-tile-editor.png: Heatmap tab selected in the chart editor with ServiceName:"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 the View in Event Deltas action.

Validation

Walked the flow end to end on play-clickstack.clickhouse.com:

  • Editor source dropdown returns only ClickPy Traces and Demo Traces when Heatmap is selected; logs/metrics sources do not appear.
  • Pre-fill: Value=(Duration)/1e6, Count=count() populate on source selection.
  • Cell click on the rendered tile opens the View in Event Deltas action; selecting it lands on /search?source=...&where=ServiceName%3A%22payment%22&from=...&to=...&mode=delta with the data source, Where clause, and time range carried over, and the Event Deltas analysis mode panel selected.

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 ClickHouse#6146

Refs hyperdxio/hyperdx#2107
@alex-fedotyev alex-fedotyev requested a review from a team as a code owner May 4, 2026 22:41
@vercel
Copy link
Copy Markdown

vercel Bot commented May 4, 2026

@alex-fedotyev is attempting to deploy a commit to the ClickHouse Team on Vercel.

A member of the Team first needs to authorize it.

@CLAassistant
Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

@alex-fedotyev
Copy link
Copy Markdown
Contributor Author

Re-opened as #6151 from an in-repo branch so Vercel previews authorize automatically. Same content; broken link event-deltas#customize -> event_deltas#customize fixed there.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document Heatmap chart type in dashboards

2 participants