> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Visualizations and dashboards with ClickStack
> Visualizations and dashboards with ClickStack
export const Image = ({img, alt, size}) => {
return
;
};
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.
Visualizations can be created from traces, metrics, logs, or any user-defined wide event schemas.
Creating visualizations
The **Chart Explorer** interface in HyperDX allows you to visualize metrics, traces, and logs over time, making it easy to create quick visualizations for data analysis. This interface is also reused when creating dashboards. The following section walks through the process of creating a visualization using Chart Explorer.
Each visualization begins by selecting a **data source**, followed by a **metric**, with optional **filter expressions** and **group by** fields. Conceptually, visualizations in HyperDX map to a SQL `GROUP BY` query under the hood — you define metrics to aggregate across selected dimensions.
**AI-powered chart generation**
ClickStack also supports creating charts from natural language prompts using the [text-to-chart](/clickstack/text-to-chart) feature. Describe what you want to see, and ClickStack generates the visualization automatically.
For example, you might chart the number of errors (`count()`) grouped by service name.
For the examples below, we use the remote dataset available at [sql.clickhouse.com](https://sql.clickhouse.com), described in the guide ["Remote Demo Dataset"](/clickstack/example-datasets/remote-demo-data). **You can also reproduce these examples by visiting [play-clickstack.clickhouse.com](https://play-clickstack.clickhouse.com).**
Navigate to Chart Explorer
Select `Chart Explorer` from the left menu.
Create visualization
In the example below, we chart the average request duration over time per service name. This requires the user to specify a metric, a column (which can be a SQL expression), and an aggregation field.
Select the `Line/Bar` visualization type from the top menu, followed by the `Traces` (or `Demo Traces` if using [play-clickstack.clickhouse.com](https://play-clickstack.clickhouse.com)) dataset. Complete the following values:
* Metric: `Average`
* Column: `Duration/1000`
* Where: ``
* Group By: `ServiceName`
* Alias: `Average Time`
Note that you can filter events using either a SQL `WHERE` clause or Lucene syntax and set the time frame over which events should be visualized. Multiple series are also supported.
For example, filter by the service `frontend` by adding the filter `ServiceName:"frontend"`. Add a second series for the count of events over time with the alias `Count` by clicking `Add Series`.
To build a series similar to an existing one, you can duplicate it instead of starting from scratch. Click the copy icon (`Duplicate series`) on a series row to insert a copy directly below. The copy keeps the source series' settings, such as the metric, column, and filter. You then change only the fields that differ (for example the aggregation) and give the copy its own alias. Duplicating is available wherever multiple series are supported. It is hidden for visualization types that allow only one series, such as `Number`, `Pie`, and `Heatmap`.
To build a series similar to an existing one, you can duplicate it instead of starting from scratch. Click the copy icon (`Duplicate series`) on a series row to insert a copy directly below. The copy keeps the source series' settings, such as the metric, column, and filter. You then change only the fields that differ (for example the aggregation) and give the copy its own alias. Duplicating is available wherever multiple series are supported. It is hidden for visualization types that allow only one series, such as `Number`, `Pie`, and `Heatmap`.
Visualizations can be created from any data source — metrics, traces, or logs. ClickStack treats all of these as wide events. Any **numeric column** can be charted over time, and **string**, **date**, or **numeric** columns can be used for groupings.
This unified approach allows you to build dashboards across telemetry types using a consistent, flexible model.
Creating dashboards
Dashboards provide a way to group related visualizations, enabling you to compare metrics and explore patterns side by side to identify potential root causes in your systems. These dashboards can be used for ad-hoc investigations or saved for ongoing monitoring.
Global filters can be applied at the dashboard level, automatically propagating to all visualizations within that dashboard. This allows for consistent drill-down across charts and simplifies correlation of events across services and telemetry types.
We create a dashboard with two visualizations below using the log and trace data sources. These steps can be reproduced on [play-clickstack.clickhouse.com](https://play-clickstack.clickhouse.com) or locally by connecting to the dataset hosted on [sql.clickhouse.com](https://sql.clickhouse.com), as described in the guide ["Remote Demo Dataset"](/clickstack/example-datasets/remote-demo-data).
Navigate to Dashboards
Select `Dashboards` from the left menu. Then click `New Dashboard` to create a temporary or saved dashboard.
Create a visualization – average request time by service
Select `Add New Tile` to open the visualization creation panel.
Select the `Line/Bar` visualization type from the top menu, followed by the `Traces` (or `Demo Traces` if using [play-clickstack.clickhouse.com](https://play-clickstack.clickhouse.com)) dataset. Complete the following values to create a chart showing the average request duration over time per service name:
* Chart Name: `Average duration by service`
* Metric: `Average`
* Column: `Duration/1000`
* Where: ``
* Group By: `ServiceName`
* Alias: `Average Time`
Click the **play** button before clicking `Save`.
Resize the visualization to occupy the full width of the dashboard.
Create a visualization – events over time by service
Select `Add New Tile` to open the visualization creation panel.
Select the `Line/Bar` visualization type from the top menu, followed by the `Logs` (or `Demo Logs` if using [play-clickstack.clickhouse.com](https://play-clickstack.clickhouse.com)) dataset. Complete the following values to create a chart showing the count of events over time per service name:
* Chart Name: `Event count by service`
* Metric: `Count of Events`
* Where: ``
* Group By: `ServiceName`
* Alias: `Count of events`
Click the **play** button before clicking `Save`.
Resize the visualization to occupy the full width of the dashboard.
Add a heatmap tile for span duration
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`](/clickstack/managing/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](/clickstack/features/event-deltas#customize) on the Event Deltas page. The same drawer is reused.
Click `Run` to preview the chart, then `Save`.
The saved tile renders as a heatmap on the dashboard. Hover any cell to see the bucket bounds and event count.
**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
Click any cell on a rendered heatmap tile to open a **View in Event Deltas** action.
Selecting it opens the [Event Deltas](/clickstack/features/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
Lucene or SQL filters, along with the time range, can be applied at the dashboard level and will automatically propagate to all visualizations.
To demonstrate, apply the Lucene filter `ServiceName:"frontend"` to the dashboard and modify the time window to cover the Last 3 hours. Note how the visualizations now reflect data only from the `frontend` service.
The dashboard will be auto-saved. To set the dashboard name, select the title and modify it before clicking `Save Name`.
Dashboards - editing visualizations
To remove, edit, or duplicate a visualization, hover over it and use the corresponding action buttons.
Tile display settings
Each tile has a **Display Settings** drawer for options that control how its value is rendered. Open it from the tile editor by clicking **Display Settings**. The available options depend on the visualization type.
Number tiles can show a **background chart**: a trend sparkline drawn behind the value, so its movement over the selected time range is visible at a glance. This is useful for SLO and error-budget tiles, where how a value is trending matters as much as its current reading.
With a number tile selected, open **Display Settings** and set **Background chart** to **Line** or **Area** (or **None** to turn it off). The sparkline is derived from a time-bucketed version of the tile's query, so no extra configuration is needed. It inherits the tile color by default; set a **Background color** to override it with a specific palette color.
Background charts apply to query-builder number tiles. Raw SQL number tiles return a single value with no time dimension to bucket, so the option appears but is disabled for them.
Dashboard - Listing and search
Dashboards are accessible on the dashboards page. They are organized by tag, with built-in search and filtering to quickly locate specific dashboards.
Dashboards can be favorited for easy access on the sidebar and at the top of the listing page. Favorites are individual to each user.
Dashboards - tagging
You can add tags to dashboards and saved searches to help organize them.
Tags provide a flexible way to categorize and filter based on your needs.
* **Organization**: Tags appear in the left sidebar, where dashboards and saved searches are grouped by their assigned tags
* **Multiple tags**: You can add one or more tags to a single item for better categorization
* **Auto-creation**: If you assign a tag that doesn't exist yet, it will be automatically created
* **Easy management**: You can add or remove tags at any time to adjust your organization structure
This makes it easy to find related items and maintain an organized workspace as your collection grows.
You can also select multiple tags to filter and view items across different categories:
Custom filters
In addition to the [free-text filters](#filter-dashboards) available on all dashboards, saved dashboards support custom dropdown filters populated by data queried from ClickHouse. These provide reusable, point-and-click filter controls so that dashboard viewers can filter without writing expressions manually.
The following steps demonstrate adding a custom filter to the dashboard created in the ["Creating dashboards"](#creating-dashboards) section.
Open the Edit Filters dialog
Open a saved dashboard and select **Edit Filters** from the toolbar.
Add a new filter
Click **Add new filter**. Configure the filter by providing a **Name**, selecting a **Data source**, and entering a **Filter expression** — a SQL column or expression whose distinct values will populate the dropdown. Click **Save filter**.
For example, to add a service filter for trace data, use `ServiceName` as the filter expression with the `Traces` data source. The "Dropdown values filter" is optional, and provides a way to restrict which values appear in the dropdown.
The Filters modal shows all configured filters for the dashboard. From here you can edit or delete existing filters, or add additional ones.
Use the filter
Close the Filters modal. The new dropdown filter appears below the search bar. Click it to see the available values, then select one to filter all visualizations on the dashboard.
(Optional) Save filter values as default
To persist a filter selection as the dashboard default, choose **Save Query & Filters as Default** from the dashboard menu. The dashboard will always open with the selected filters applied. To reset, select **Remove Default Query & Filters** from the same menu.
Custom dropdown filters are available on saved dashboards. For an example of this pattern in action, see the [Kubernetes dashboard](#kubernetes-dashboard), which provides built-in dropdown filters for Pod, Deployment, Node name, Namespace, and Cluster.
Drilldown to search
Dashboard tiles support drilldown to the Search page. Click on a data point in a visualization to open a context menu with the following options:
* **View All Events** — navigates to the Search page showing all events from the selected time window.
* **Filter by group** — navigates to the Search page filtered to a specific series.
This is useful for investigating specific spikes or anomalies spotted in a dashboard — you can quickly pivot from an aggregated view to the underlying individual events.
Presets
HyperDX is deployed with out-of-the-box dashboards.
ClickHouse dashboard
This dashboard provides visualizations for monitoring ClickHouse. To navigate to this dashboard, select it from the left menu.
This dashboard uses tabs to separate monitoring of **Selects**, **Inserts**, and **ClickHouse Infrastructure**.
**Required system table access**
This dashboard queries the ClickHouse [system tables](/reference/system-tables/index) to expose key metrics. The following grants are required:
`GRANT SHOW COLUMNS, SELECT(CurrentMetric_MemoryTracking, CurrentMetric_S3Requests, ProfileEvent_OSCPUVirtualTimeMicroseconds, ProfileEvent_OSReadChars, ProfileEvent_OSWriteChars, ProfileEvent_S3GetObject, ProfileEvent_S3ListObjects, ProfileEvent_S3PutObject, ProfileEvent_S3UploadPart, event_time) ON system.metric_log`
`GRANT SHOW COLUMNS, SELECT(active, database, partition, rows, table) ON system.parts`
`GRANT SHOW COLUMNS, SELECT(event_date, event_time, memory_usage, normalized_query_hash, query, query_duration_ms, query_kind, read_rows, tables, type, written_bytes, written_rows) ON system.query_log`
`GRANT SHOW COLUMNS, SELECT(event_date, event_time, hostname, metric, value) ON system.transposed_metric_log`
Services dashboard
The Services dashboard displays currently active services based on trace data. This requires you to have collected traces and configured a valid Traces data source.
Service names are auto-detected from the trace data, with a series of prebuilt visualizations organized across three tabs: HTTP Services, Database, and Errors.
Visualizations can be filtered using Lucene or SQL syntax, and the time window can be adjusted for focused analysis.
Kubernetes dashboard
This dashboard allows you to explore Kubernetes events collected via OpenTelemetry. It includes advanced filtering options, enabling you to filter by Kubernetes Pod, Deployment, Node name, Namespace, and Cluster, as well as perform free-text searches.
Kubernetes data is organized across three tabs for easy navigation: Pods, Nodes, and Namespaces.