> ## Documentation Index > Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Visualizations and dashboards with ClickHouse Observability > Visualizations and dashboards with ClickHouse Observability ClickHouse Observability supports visualizing events, with built-in support for charting in the UI. 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 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 map to a SQL `GROUP BY` query under the hood — you define metrics to aggregate across selected dimensions. > [!TIP] > > **AI-powered chart and dashboard generation** > > ClickHouse Observability also supports creating charts from natural language prompts using the [text-to-chart](https://clickhouse.com/docs/clickstack/observability/text-to-chart.md) feature. Describe what you want to see, and the UI generates the visualization automatically. To generate a complete dashboard with multiple tiles, use [Text-to-Dashboard](https://clickhouse.com/docs/clickstack/observability/text-to-dashboard.md). 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). **You can also reproduce these examples by visiting [play-clickstack.clickhouse.com](https://play-clickstack.clickhouse.com).** **1. Navigate to Chart Explorer** Select `Chart Explorer` from the left menu. ![Chart Explorer](https://mintcdn.com/private-7c7dfe99/uAzQoYEGwuyhrO3W/images/use-cases/observability/clickstack-visualization-1.webp?fit=max\&auto=format\&n=uAzQoYEGwuyhrO3W\&q=85\&s=13d1720243bd850e6454364ffbca0bbf) **2. 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 `Time Series` 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` ![Simple visualization](https://mintcdn.com/private-7c7dfe99/uAzQoYEGwuyhrO3W/images/use-cases/observability/clickstack-visualization-2.webp?fit=max\&auto=format\&n=uAzQoYEGwuyhrO3W\&q=85\&s=6c0420fb5542b7a9afb965d24fb1dacb) 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`. ![Simple visualization 2](https://mintcdn.com/private-7c7dfe99/uAzQoYEGwuyhrO3W/images/use-cases/observability/clickstack-visualization-3.webp?fit=max\&auto=format\&n=uAzQoYEGwuyhrO3W\&q=85\&s=1ca594d72a0d63c4d9987c0039494f30) 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`. ![The Duplicate series copy icon and its tooltip on a chart series row](https://mintcdn.com/private-7c7dfe99/uAzQoYEGwuyhrO3W/images/use-cases/observability/clickstack-duplicate-series.webp?fit=max\&auto=format\&n=uAzQoYEGwuyhrO3W\&q=85\&s=400991cc856edb5f51d5c8694910f08c) > [!NOTE] > > Visualizations can be created from any data source — metrics, traces, or logs. ClickHouse Observability 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). **1. Navigate to Dashboards** Select `Dashboards` from the left menu. Then click `New Dashboard` to create a temporary or saved dashboard. ![Dashboards page with the New Dashboard menu showing Saved Dashboard and Temporary Dashboard options](https://mintcdn.com/private-7c7dfe99/dW6bcEakZdn3a5oP/images/clickstack/observability-new-dashboard.png?fit=max\&auto=format\&n=dW6bcEakZdn3a5oP\&q=85\&s=f51cf31de126909422f9423d1c2888ab) **2. Create a visualization – average request time by service** Select `Add` to open the visualization creation panel. Select the `Time Series` 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 `Run` to preview the chart, then click `Save`. ![Time Series chart editor showing average duration grouped by ServiceName](https://mintcdn.com/private-7c7dfe99/dW6bcEakZdn3a5oP/images/clickstack/observability-dashboard-average-duration.png?fit=max\&auto=format\&n=dW6bcEakZdn3a5oP\&q=85\&s=c19d4f551587e70c3b319865b18da9f3) Resize the visualization to occupy the full width of the dashboard. ![Dashboard with the Average duration by service chart spanning the full width](https://mintcdn.com/private-7c7dfe99/dW6bcEakZdn3a5oP/images/clickstack/observability-dashboard-duration-tile.png?fit=max\&auto=format\&n=dW6bcEakZdn3a5oP\&q=85\&s=ac8dc97c3cae7bad8b9c56737371cadb) **3. Create a visualization – events over time by service** Select `Add` to open the visualization creation panel. Select the `Time Series` 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 `Run` to preview the chart, then click `Save`. ![Time Series chart editor showing event counts grouped by ServiceName](https://mintcdn.com/private-7c7dfe99/dW6bcEakZdn3a5oP/images/clickstack/observability-dashboard-event-count.png?fit=max\&auto=format\&n=dW6bcEakZdn3a5oP\&q=85\&s=2a2b7ff2c3c28dacaf23d689094ea985) Resize the visualization to occupy the full width of the dashboard. ![Dashboard with full-width charts showing average duration and event count by service](https://mintcdn.com/private-7c7dfe99/dW6bcEakZdn3a5oP/images/clickstack/observability-dashboard-two-charts.png?fit=max\&auto=format\&n=dW6bcEakZdn3a5oP\&q=85\&s=6e304fe76602ecce3ae3170377a87240) **4. 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`. 2. Choose the `Heatmap` visualization type from the top menu. The data source dropdown only shows sources whose [source type is `Traces`](https://clickhouse.com/docs/clickstack/observability/managing/config#datasource-settings). 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 span durations for the `payment` service, with most spans concentrated around one millisecond and scattered slower spans above them. 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](https://clickhouse.com/docs/clickstack/observability/features/event-deltas.md#customize) on the Event Deltas page. The same drawer is reused. Click `Run` to preview the chart, then `Save`. ![Heatmap editor showing payment service span durations with a ServiceName filter and Display Settings button](https://mintcdn.com/private-7c7dfe99/dW6bcEakZdn3a5oP/images/clickstack/observability-dashboard-heatmap-editor.png?fit=max\&auto=format\&n=dW6bcEakZdn3a5oP\&q=85\&s=f56b9d21be26b27b4c7a233d8a274b42) The saved tile renders as a heatmap on the dashboard. Hover any cell to see the bucket bounds and event count. ![Dashboard with a payment span duration heatmap tile and a tooltip showing duration and event count](https://mintcdn.com/private-7c7dfe99/dW6bcEakZdn3a5oP/images/clickstack/observability-dashboard-heatmap-tile.png?fit=max\&auto=format\&n=dW6bcEakZdn3a5oP\&q=85\&s=720caf189b5c0c1461fa39900ec8d91f) > [!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 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](https://mintcdn.com/private-7c7dfe99/LCIbqddLfKHZZnfk/images/clickstack/dashboards/heatmap-tile-drilldown.webp?fit=max\&auto=format\&n=LCIbqddLfKHZZnfk\&q=85\&s=69b216a5037e652dc93c68e4c533452d) Selecting it opens the [Event Deltas](https://clickhouse.com/docs/clickstack/observability/features/event-deltas.md) 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. **5. 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. ![Dashboard filtered to the frontend service, showing average duration and event count charts](https://mintcdn.com/private-7c7dfe99/dW6bcEakZdn3a5oP/images/clickstack/observability-dashboard-filter.png?fit=max\&auto=format\&n=dW6bcEakZdn3a5oP\&q=85\&s=06b8c12f86a3a108bf9a31692027bd56) To demonstrate, apply the Lucene filter `ServiceName:"frontend"` to the dashboard and select a time window containing data. 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`. ![Dashboard with the My Dashboard name selected for editing](https://mintcdn.com/private-7c7dfe99/dW6bcEakZdn3a5oP/images/clickstack/observability-dashboard-save-name.png?fit=max\&auto=format\&n=dW6bcEakZdn3a5oP\&q=85\&s=43894612e96899c7c85688dd3e27f65b) ## Dashboards - editing visualizations To remove, edit, or duplicate a visualization, hover over it and use the corresponding action buttons. ![Dashboard chart menu showing Duplicate, Edit, and Delete options](https://mintcdn.com/private-7c7dfe99/dW6bcEakZdn3a5oP/images/clickstack/observability-dashboard-edit.png?fit=max\&auto=format\&n=dW6bcEakZdn3a5oP\&q=85\&s=cccf6150b9209b2d893fba39603938f0) ### 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 tile color Number tiles support a static **Color** choice from the curated chart palette. With a number tile selected, open **Display Settings** and use the **Color** control (labeled **Number tile color** for accessibility) to pick a swatch, or clear the selection to use the default text color. Colors are stored as palette tokens, not raw hex values, so the same tile reflows correctly across light, dark, and IDE themes. **Categorical tokens** (multi-series hues): | Token | Label | | - | - | | `chart-blue` | Blue | | `chart-orange` | Orange | | `chart-red` | Red | | `chart-cyan` | Cyan | | `chart-green` | Green | | `chart-pink` | Pink | | `chart-purple` | Purple | | `chart-light-blue` | Light Blue | | `chart-brown` | Brown | | `chart-gray` | Gray | **Semantic tokens** (status-oriented): | Token | Label | | - | - | | `chart-success` | Success | | `chart-warning` | Warning | | `chart-error` | Error | Use semantic tokens when the number represents a status (for example error count in `chart-error`, or a healthy rate in `chart-success`). Use categorical tokens when you want visual distinction between related KPI tiles without implying status. Older configs may still store legacy numeric tokens (`chart-1` through `chart-10`). The UI maps those to the hue-named tokens above when loading a dashboard. The same palette powers optional **color rules** in the same drawer: ordered conditions evaluated against the displayed value (last match wins). When no rule matches, the static color applies, then the default text color. #### Number tile background chart 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. ![Display Settings drawer for a number tile, with Background chart set to Area](https://mintcdn.com/private-7c7dfe99/LCIbqddLfKHZZnfk/images/clickstack/dashboards/number-tile-background-chart.webp?fit=max\&auto=format\&n=LCIbqddLfKHZZnfk\&q=85\&s=6d984f5c79b28687157d32c8f74cc955) 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. Table tiles can stripe their rows with **Alternate Row Background**, which tints every other row so wide tables are easier to scan. It is off by default. With a table tile selected, open **Display Settings** and turn on **Alternate Row Background**. Striping is purely visual, so it works on both query-builder and raw SQL table tiles. ![Display Settings drawer for a table tile, with Alternate Row Background turned on](https://mintcdn.com/private-7c7dfe99/LCIbqddLfKHZZnfk/images/clickstack/dashboards/table-tile-display-settings.webp?fit=max\&auto=format\&n=LCIbqddLfKHZZnfk\&q=85\&s=c2f43977a5f5f04627216dd51e5da2b2) Table tiles also keep a separator between the header row and the data as you scroll, so the column headers stay distinct. #### Dashboards API: number tile color When creating or updating dashboards through the external API (`POST` / `PUT` `/api/v2/dashboards`), set `color` on a builder number-tile config to a palette token. Raw hex values are rejected. ```json theme={null} { "name": "Error rate KPIs", "tiles": [ { "id": "65f5e4a3b9e77c001a222222", "name": "Errors", "x": 0, "y": 0, "w": 6, "h": 4, "config": { "displayType": "number", "sourceId": "", "select": [ { "aggFn": "count", "where": "SeverityText:error", "whereLanguage": "lucene", "alias": "Errors" } ], "color": "chart-error", "backgroundChart": { "type": "area" } } } ] } ``` `color` accepts any token from the categorical and semantic lists above (for example `chart-blue` or `chart-success`). Optional `backgroundChart.color` overrides the sparkline color with the same token enum. See the [API reference](https://clickhouse.com/docs/clickstack/observability/api-reference) for authentication and base URLs. ## 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. ![Dashboard listing with a search field, sorting controls, and My Dashboard containing three tiles](https://mintcdn.com/private-7c7dfe99/dW6bcEakZdn3a5oP/images/clickstack/observability-dashboard-listing.png?fit=max\&auto=format\&n=dW6bcEakZdn3a5oP\&q=85\&s=db92288eaedb42c659f890c90711fbb1) ## 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. #### How tags work * **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. Open the dashboard's **Tags** menu to select or create tags. You can assign multiple tags to the same dashboard, as shown below: ![Dashboard Tags menu with API and MONITORING selected](https://mintcdn.com/private-7c7dfe99/dW6bcEakZdn3a5oP/images/clickstack/observability-dashboard-tags.png?fit=max\&auto=format\&n=dW6bcEakZdn3a5oP\&q=85\&s=3e17a5ed03a1f5e265af8b575a8c4c6e) ## Custom filters and variables 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. ![Services dropdown filter showing available service names](https://mintcdn.com/private-7c7dfe99/LCIbqddLfKHZZnfk/images/clickstack/dashboards/filter-dropdown.webp?fit=max\&auto=format\&n=LCIbqddLfKHZZnfk\&q=85\&s=3d214d18194d5e197d9e8cf0c9e9fbc8) Each filter allows the viewer to choose one or more values, and does one or both of the following with them: * **Broadcast** — applies the selection as a filter condition on matching tiles. Tiles do not need to be updated to reference the filter. * **Variable** — exposes the selection to tile queries as `$variableName`, so each tile decides where and how the value is used. A filter must do at least one of the two. Broadcast is enabled by default when creating a filter. The following steps demonstrate adding a filter to the dashboard created in the ["Creating dashboards"](#creating-dashboards) section. **1. Open the Edit Filters dialog** Open a saved dashboard and select **Edit Filters and Variables** from the toolbar. ![Edit Filters button in the dashboard toolbar](https://mintcdn.com/private-7c7dfe99/jdRTe32x5rK1EpNX/images/clickstack/dashboards/edit-filters.webp?fit=max\&auto=format\&n=jdRTe32x5rK1EpNX\&q=85\&s=9f0295fa4b80a2117ef2bdff9c2057e6) **2. Add a new filter** Click **Add new filter**. Configure the filter by providing a **Display 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. ![Add filter dialog with Display Name, Data source, and Filter expression fields](https://mintcdn.com/private-7c7dfe99/jdRTe32x5rK1EpNX/images/clickstack/dashboards/add-filter.webp?fit=max\&auto=format\&n=jdRTe32x5rK1EpNX\&q=85\&s=145e113c3a534364ca1de92db972c2aa) The same dialog also controls whether the filter [broadcasts](#broadcast-filters) its value and whether it is [available as a variable](#dashboard-variables), both described below. The **Filters and Variables** dialog shows all configured filters for the dashboard. From here you can edit or delete existing filters, or add additional ones. ![Filters and Variables dialog showing a Services filter using Demo Traces and broadcasting to all sources](https://mintcdn.com/private-7c7dfe99/dW6bcEakZdn3a5oP/images/clickstack/observability-dashboard-saved-filters.png?fit=max\&auto=format\&n=dW6bcEakZdn3a5oP\&q=85\&s=7b0a6092220aab03d3adfb72c7d8d79d) **3. Use the filter** Close the **Filters and Variables** dialog. 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. ![Dashboard filtered to the accounting service with the Services dropdown open](https://mintcdn.com/private-7c7dfe99/dW6bcEakZdn3a5oP/images/clickstack/observability-dashboard-filtered.png?fit=max\&auto=format\&n=dW6bcEakZdn3a5oP\&q=85\&s=414f8aad5e868ea4139b70cf17d22968) **4. (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. ![Dashboard menu showing Save Query & Filters as Default with the accounting service selected](https://mintcdn.com/private-7c7dfe99/dW6bcEakZdn3a5oP/images/clickstack/observability-dashboard-save-filter-values.png?fit=max\&auto=format\&n=dW6bcEakZdn3a5oP\&q=85\&s=b79040a07537636c0d1be272e74533d4) > [!NOTE] > > 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. ### Broadcasting With **Broadcast filter condition** enabled, the selected values are applied as a filter condition on the dashboard's tiles, without any tile explicitly referencing the filter. By default the condition reaches every tile. Use **Applies to sources** to restrict it to tiles that use a given set of sources — useful when the filter's expression only makes sense for some of the data on the dashboard. Chart builder tiles pick up broadcast filters automatically. Raw SQL tiles must include the [`$__filters` macro](https://clickhouse.com/docs/clickstack/observability/features/dashboards/sql-visualizations#dashboard-filter-macro) and have a source selected, since the UI cannot infer where the condition belongs in a hand-written query. ### Variables With **Available as variable** enabled, the filter's selection is also exposed to tile queries as `$variableName`. The **Variable name** defaults to the filter's display name with illegal characters removed, and can be overridden. Names must start with a letter and may contain only letters, digits, and underscores. Use a variable when broadcasting a `WHERE` condition is not what you want — for example, to put the value in a `SELECT` expression, a `HAVING` clause, or a join key, or to filter a tile on a column other than the filter's own expression. #### Referencing a variable A variable expands to the values currently selected in its dropdown. The reference form controls the rendering: | Reference | Expands to | Empty selection | | - | - | - | | `$name`, `${name}` | The selected values, in `sqlstring` or `lucene` format, depending on context. Braces delimit the name when it is followed by word characters, as in `${name}_total`. | `NULL` | | `${name:sqlstring}` | The selected values, single-quoted, comma-separated, and escaped as SQL values, eg. `'a', 'b'` | `NULL` | | `${name:csv}` | Unquoted and comma-separated: `a,b`. Not escaped for SQL. | empty string | | `${name:regex}` | A regex alternation, regex-escaped: `(a\|b)`. | `.*` | | `${name:lucene}` | An `OR` of quoted terms, for Lucene inputs: `("a" OR "b")`. | `("")` | Because `$name` renders as `NULL` before anything is selected, prefer the following macros wherever a SQL predicate is expected. Both macros expand to `1=1` while their variable has no selection, so the query stays valid: | Macro | Description | | - | - | | `$__filter($)` | Expands to `toString() IN ($variable)` when values are selected for `variable`, and `1=1` otherwise. | | `$__filter(, $)` | Expands to ` IN ($variable)` when values are selected for `variable`, and `1=1` otherwise. | | `$__conditionalAll(, $)` | Expands to `` when the variable has a selection, `1=1` otherwise. | #### Using variables in chart builder tiles Every SQL expression input in the chart builder accepts variable references: `SELECT` columns and per-series expressions, `WHERE`, `GROUP BY`, and `HAVING`. The editor autocompletes the dashboard's variables and shows what each reference expands to for the current selection. Prefer using the `$__filter` and `$__conditionalAll` macros when in SQL mode, so that queries remain valid when variable selections are empty. Macros are not available in Lucene inputs — reference raw variables there instead (eg. `ServiceName:$service`). In a Lucene input, whether the variable reference itself is quoted controls how a multi-value selection is matched. Given `$service` selected as `a,b`: | Reference | Expands to | Matching behavior | | - | - | - | | `ServiceName:$service` | `ServiceName:("a" OR "b")` | Substring match — translated to SQL as `ServiceName ILIKE '%a%' OR ServiceName ILIKE '%b%'` | | `ServiceName:"$service"` | `(ServiceName:"a" OR ServiceName:"b")` | Exact match on each selected value | Quote the variable reference — `Field:"$var"` — when the selected values should match `Field` exactly rather than as substrings. #### Using variables in SQL tiles Raw SQL tiles reference variables the same way, anywhere in the query: ```sql theme={null} SELECT $__timeInterval(TimestampTime) AS ts, count() AS count FROM otel_logs WHERE $__timeFilter(TimestampTime) AND $__filter(ServiceName, $service) AND $__conditionalAll(SeverityText NOT IN ($severity), $severity) GROUP BY ts ORDER BY ts ASC ``` See [SQL-based visualizations](https://clickhouse.com/docs/clickstack/observability/features/dashboards/sql-visualizations.md#dashboard-variables) for the full list of macros available to SQL tiles. > [!NOTE] > > Alerts on a tile that references a dashboard variable evaluate with every variable in its empty state, not the values selected on the dashboard. ## 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. * **Search** (magnifying glass beside a series) — opens the Search page for that series. * **Copy label** — copies the series label. * **Focus** — focuses on the selected series in the chart. ![Dashboard chart tooltip showing per-service values and the View All Events action](https://mintcdn.com/private-7c7dfe99/dW6bcEakZdn3a5oP/images/clickstack/observability-dashboard-drilldown.png?fit=max\&auto=format\&n=dW6bcEakZdn3a5oP\&q=85\&s=dea0ec62b69137581201cc7397b68ecc) 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 The UI includes out-of-the-box dashboards. ### 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 Service**, **Database**, and **Errors**. Visualizations can be filtered using Lucene or SQL syntax, and the time window can be adjusted for focused analysis. ![Services dashboard HTTP Service tab showing request error rate, throughput, time-consuming endpoints, and latency](https://mintcdn.com/private-7c7dfe99/dW6bcEakZdn3a5oP/images/clickstack/observability-dashboard-services.png?fit=max\&auto=format\&n=dW6bcEakZdn3a5oP\&q=85\&s=8560c27ecb8f2fa47af37c39f4639281) ### 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. ![Kubernetes dashboard Pods tab showing CPU usage, memory usage, pod status, and cluster filters](https://mintcdn.com/private-7c7dfe99/dW6bcEakZdn3a5oP/images/clickstack/observability-dashboard-kubernetes.png?fit=max\&auto=format\&n=dW6bcEakZdn3a5oP\&q=85\&s=d522c1d27df8c9ab729512e7497429fc)