diff --git a/docs/use-cases/observability/clickstack/dashboards/index.md b/docs/use-cases/observability/clickstack/dashboards/index.md index f36448b84ff..2b780780415 100644 --- a/docs/use-cases/observability/clickstack/dashboards/index.md +++ b/docs/use-cases/observability/clickstack/dashboards/index.md @@ -32,6 +32,9 @@ import filtered_dashboard from '@site/static/images/clickstack/dashboards/filter import filter_dropdown from '@site/static/images/clickstack/dashboards/filter-dropdown.png'; import save_filter_values from '@site/static/images/clickstack/dashboards/save-filter-values.png'; import drilldown from '@site/static/images/clickstack/dashboards/drilldown.png'; +import heatmap_tile_editor from '@site/static/images/clickstack/dashboards/heatmap-tile-editor.png'; +import heatmap_tile_rendered from '@site/static/images/clickstack/dashboards/heatmap-tile-rendered.png'; +import heatmap_tile_drilldown from '@site/static/images/clickstack/dashboards/heatmap-tile-drilldown.png'; import Tagging from '@site/docs/_snippets/_clickstack_tagging.mdx'; ClickStack supports visualizing events, with built-in support for charting in ClickStack UI (HyperDX). These charts can be added to dashboards for sharing with other users. @@ -145,6 +148,47 @@ Resize the visualization to occupy the full width of the dashboard. Dashboard with visuals 2 +### Add a heatmap tile for span duration {#create-a-tile-heatmap} + +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. + +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 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. +3. Pick any of your traces sources by name. The name itself is arbitrary, only the type matters. + +Once a source is selected, the heatmap pre-fills: + +- **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()` + +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 are documented in [Customize the heatmap](/use-cases/observability/clickstack/event_deltas#customize) on the Event Deltas page. The same drawer is reused. + +Click `Run` to preview the chart, then `Save`. + +Heatmap tile editor with span duration defaults pre-filled, ServiceName payment filter, and Display Settings button + +The saved tile renders as a heatmap on the dashboard. Hover any cell to see the bucket bounds and event count. + +Heatmap dashboard tile showing payment service span duration distribution over 24 hours + +:::tip Two ClickHouse queries per heatmap +The heatmap runs as two sequential queries: a small **bounds query** that resolves the value range, then a **heatmap query** that counts events per bucket. Both queries are visible in the editor under **Generated SQL** if you want to inspect or copy them. +::: + +#### Drill down to Event Deltas {#heatmap-tile-drilldown} + +Click any cell on a rendered heatmap tile to open a **View in Event Deltas** action. + +Heatmap cell click revealing the View in Event Deltas action + +Selecting it opens the [Event Deltas](/use-cases/observability/clickstack/event_deltas) view with the tile's data source, `Where` clause, and time range carried over. From there you can examine the same distribution interactively, slice by attribute to see what makes the slow spans different from the fast ones, and inspect the individual spans behind any cell, without rebuilding the query by hand. + ### Filter dashboard {#filter-dashboards} Lucene or SQL filters, along with the time range, can be applied at the dashboard level and will automatically propagate to all visualizations. diff --git a/docs/use-cases/observability/clickstack/event_deltas.md b/docs/use-cases/observability/clickstack/event_deltas.md index 084b438c3c8..0fe5611722d 100644 --- a/docs/use-cases/observability/clickstack/event_deltas.md +++ b/docs/use-cases/observability/clickstack/event_deltas.md @@ -107,6 +107,10 @@ The gear icon in the top-right of the heatmap opens the **Heatmap Settings** dra Click **Apply** to update the heatmap; the attribute analysis below follows. +:::tip Heatmap on dashboards +The same heatmap is also available as a [dashboard tile](/use-cases/observability/clickstack/dashboards#create-a-tile-heatmap), which is useful when you want to monitor the distribution shape over time outside the Event Deltas drill-down flow. +::: + ## Troubleshooting {#troubleshooting} ### Event Deltas tab isn't visible {#tab-not-visible} diff --git a/static/images/clickstack/dashboards/heatmap-tile-drilldown.png b/static/images/clickstack/dashboards/heatmap-tile-drilldown.png new file mode 100644 index 00000000000..e8be1fc0608 Binary files /dev/null and b/static/images/clickstack/dashboards/heatmap-tile-drilldown.png differ diff --git a/static/images/clickstack/dashboards/heatmap-tile-editor.png b/static/images/clickstack/dashboards/heatmap-tile-editor.png new file mode 100644 index 00000000000..2aaf98da489 Binary files /dev/null and b/static/images/clickstack/dashboards/heatmap-tile-editor.png differ diff --git a/static/images/clickstack/dashboards/heatmap-tile-rendered.png b/static/images/clickstack/dashboards/heatmap-tile-rendered.png new file mode 100644 index 00000000000..93dce7af3fb Binary files /dev/null and b/static/images/clickstack/dashboards/heatmap-tile-rendered.png differ