
Welcome to the April edition of What's New in ClickStack.

April was a release focused on tightening the core experience across querying, alerting, and dashboards.

SQL-powered alerts landed this month, rounding out the SQL-native observability workflow we [started building last month](https://clickhouse.com/blog/whats-new-in-clickstack-march-2026#sql-charts-with-grafana-style-macros). You can now move from writing queries and building dashboards directly into alerting, without switching query languages or maintaining separate rule pipelines.

Under the hood, we also redesigned the default logs schema around ClickHouse's text index. Combined with a follow-up optimization for map attribute filtering, this delivers up to Nx faster performance in our benchmarks for common search and filtering workloads.

Autocomplete also got a major overhaul. Metadata discovery now runs through materialized-view rollups behind the scenes, making suggestions feel substantially faster and more responsive, especially on larger datasets.

Heatmaps are now a first-class chart type available anywhere in dashboards, instead of being limited to Event Deltas. This makes it much easier to visualize latency distributions, density, and outliers directly alongside the rest of your operational views.

Alongside the larger changes, April also included a long list of quality-of-life improvements across alerting, table layouts, pie charts, and per-series number formatting.

## Open House {#open-house}

If you're attending [Open House](https://clickhouse.com/openhouse/san-francisco), we'll also have a dedicated observability track this year with talks from several ClickStack developers and contributors, alongside customer sessions from teams covering how they're running observability workloads on ClickHouse in production.

If you can't make it live, all sessions will be recorded and published afterward.

## Contributing {#contributing}

As always, thank you to our open source contributors and users whose feedback continues to shape ClickStack.

If code contributions are not your thing, we welcome documentation improvements, ideas, feature suggestions, bug reports, and general feedback via the [repository](https://github.com/hyperdxio/hyperdx/tree/v2). Every contribution, big or small, helps make the stack better for the entire community.

Interested in seeing how ClickHouse works on your observability data? Get started with Managed ClickStack in ClickHouse Cloud in minutes and receive $300 in free credits.

Get started today

## Alerts on raw SQL charts {#alerts-on-raw-sql-charts}

SQL alerting introduces a first-class way to express observability logic that doesn't fit inside a query builder. Users can now build charts and alerts directly from arbitrary ClickHouse SQL queries, unlocking more advanced analysis directly inside the ClickStack UI.

Static thresholding works fine until teams start doing anything even slightly statistical. Rolling baselines, percentile drift, grouped anomaly checks, or historical comparisons all become awkward once the alert itself is constrained by a UI model. In practice, many users ended up pushing advanced alerting logic into external systems or custom pipelines despite already storing the data in ClickHouse.

SQL alerting builds directly on the [SQL charting support introduced last month](https://clickhouse.com/blog/whats-new-in-clickstack-march-2026#sql-charts-with-grafana-style-macros). Once arbitrary SQL could be expressed in dashboards and visualizations, extending this into alerting became a natural next step.

SQL queries for alerts can be used to compute rolling baselines over previous intervals, calculate standard deviation bands, and compare current behavior against historical trends. Beyond this, queries can encapsulate even more complex conditions. For example, queries can emit `1` only when something becomes anomalous. The alert itself then becomes extremely simple: trigger when the query returns `1`, with the query capturing the conditions.

ClickHouse window functions make these kinds of workflows straightforward to express. For example, this query builds a rolling statistical baseline for error volume and returns `1` whenever the current interval deviates significantly from recent historical behavior.

<pre><code type='click-ui' language='sql'>
WITH buckets AS (
  SELECT
    $__timeInterval(Timestamp) AS ts,
    count() AS bucket_count
  FROM $__sourceTable
  WHERE Timestamp >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64})
                     - toIntervalSecond($__interval_s * 30)
    AND Timestamp < fromUnixTimestamp64Milli({endDateMilliseconds:Int64})
    AND SeverityText = 'error'
    AND $__filters
  GROUP BY ts
  ORDER BY ts
  WITH FILL STEP toIntervalSecond($__interval_s)
),
baselines AS (
  SELECT
    ts,
    bucket_count,
    avg(bucket_count) OVER (
      ORDER BY ts ROWS BETWEEN 30 PRECEDING AND 1 PRECEDING
    ) AS rolling_avg,
    stddevPop(bucket_count) OVER (
      ORDER BY ts ROWS BETWEEN 30 PRECEDING AND 1 PRECEDING
    ) AS rolling_stddev
  FROM buckets
)
SELECT
  ts,
  if(bucket_count > rolling_avg + 2 * rolling_stddev, 1, 0) AS anomaly
FROM baselines
WHERE rolling_avg IS NOT NULL
  AND ts >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64})
ORDER BY ts ASC;
</code></pre>

![](/uploads/clickstack_apr2026_image2_6ceaa5360e.png)

Alerts also support the same `$__filters`, `$__sourceTable`, and `{intervalSeconds:Int64}` macros already used by SQL visualizations, including Grafana-compatible interval handling. This means alert queries automatically inherit the dashboard and source filter context without additional wiring.

For a deeper walkthrough of rolling baselines, anomaly detection patterns, and supported macros, see the dedicated [SQL Charting and Alerting](https://clickhouse.com/blog/clickstack-sql-charting-and-alerting) post. Full macro and parameter documentation is also available in the [alerts documentation](https://clickhouse.com/docs/use-cases/observability/clickstack/alerts).

## A new default logs schema {#a-new-default-logs-schema}

After benchmarking and profiling common observability workloads, we redesigned the default `otel_logs` schema used by ClickStack.

We originally started this work while profiling a handful of recurring query patterns that kept showing up in benchmarks and production traces. After a while, it became clear the issue was no longer isolated to settings tuning. The default schema itself needed another pass, particularly around indexing strategy and ordering layout.

> We'll be covering the benchmarking process, tooling, and methodology in more detail separately, including some of the internal benchmarking utilities we may eventually open source. We'll also be [discussing the work at Open House](https://clickhouse.com/openhouse/san-francisco) for users interested in the deeper storage and indexing details behind the changes.

The new schema:

<pre><code type='click-ui' language='sql'>
CREATE TABLE IF NOT EXISTS otel_logs
(
  `Timestamp` DateTime64(9) CODEC(Delta(8), ZSTD(1)),
  `TraceId` String CODEC(ZSTD(1)),
  `SpanId` String CODEC(ZSTD(1)),
  `TraceFlags` UInt8,
  `SeverityText` LowCardinality(String) CODEC(ZSTD(1)),
  `SeverityNumber` UInt8,
  `ServiceName` LowCardinality(String) CODEC(ZSTD(1)),
  `Body` String CODEC(ZSTD(1)),
  `ResourceSchemaUrl` LowCardinality(String) CODEC(ZSTD(1)),
  `ResourceAttributes` Map(LowCardinality(String), String) CODEC(ZSTD(1)),
  `ScopeSchemaUrl` LowCardinality(String) CODEC(ZSTD(1)),
  `ScopeName` String CODEC(ZSTD(1)),
  `ScopeVersion` LowCardinality(String) CODEC(ZSTD(1)),
  `ScopeAttributes` Map(LowCardinality(String), String) CODEC(ZSTD(1)),
  `LogAttributes` Map(LowCardinality(String), String) CODEC(ZSTD(1)),
  `EventName` String CODEC(ZSTD(1)),
  `__hdx_materialized_k8s.cluster.name` LowCardinality(String) MATERIALIZED
      ResourceAttributes['k8s.cluster.name'] CODEC(ZSTD(1)),
  -- ... seven more __hdx_materialized_* columns omitted for brevity
  INDEX idx_trace_id          TraceId                       TYPE text(tokenizer = 'array'),
  INDEX idx_res_attr_key      mapKeys(ResourceAttributes)   TYPE text(tokenizer = 'array'),
  INDEX idx_res_attr_value    mapValues(ResourceAttributes) TYPE text(tokenizer = 'array'),
  INDEX idx_scope_attr_key    mapKeys(ScopeAttributes)      TYPE text(tokenizer = 'array'),
  INDEX idx_scope_attr_value  mapValues(ScopeAttributes)    TYPE text(tokenizer = 'array'),
  INDEX idx_log_attr_key      mapKeys(LogAttributes)        TYPE text(tokenizer = 'array'),
  INDEX idx_log_attr_value    mapValues(LogAttributes)      TYPE text(tokenizer = 'array'),
  INDEX idx_lower_body        lower(Body)                   TYPE text(tokenizer = 'splitByNonAlpha')
)
ENGINE = MergeTree
PARTITION BY toDate(Timestamp)
ORDER BY (toStartOfFiveMinutes(Timestamp), ServiceName, Timestamp)
TTL toDateTime(Timestamp) + INTERVAL 14 DAYS
SETTINGS index_granularity = 8192, ttl_only_drop_parts = 1,
         enable_block_number_column = 1, enable_block_offset_column = 1;
</code></pre>

The primary key is now `(toStartOfFiveMinutes(Timestamp), ServiceName, Timestamp)`. The previous schema carried both `Timestamp` and a secondary `TimestampTime DateTime DEFAULT toDateTime(Timestamp)` column, with the latter used in the ordering key to improve pruning at second-level granularity.

With the new five-minute bucket layout, that extra column is no longer necessary and has been removed entirely. The coarser leading bucket keeps [adjacent log rows physically grouped](https://clickhouse.com/docs/guides/best-practices/sparse-primary-indexes) for common time-range queries while still allowing efficient pruning during scans.

The skip indices strategy has changed significantly as well. Previous schemas relied primarily on `bloom_filter` indexes over attribute maps alongside a `tokenbf_v1` index on the `Body` column. The new schema instead adopts [ClickHouse's Full-text index](https://clickhouse.com/docs/engines/table-engines/mergetree-family/textindexes) across both keys and values for `ResourceAttributes`, `ScopeAttributes`, and `LogAttributes`, while a dedicated text index using the `splitByNonAlpha` tokenizer now covers `lower(Body)`.

In our benchmarks, the `text` index consistently outperformed the previous bloom-filter approach for search-oriented workloads while adding minimal ingest overhead. These new indexes also enable the attribute-search optimizations covered in the following section.

> For users running ClickHouse versions prior to 26.2, where full-text search indexes became generally available, ClickStack automatically falls back to a compatibility schema variant using `bloom_filter` and `tokenbf_v1` indexes while preserving UI compatibility and the same query semantics.

Across all of our sample queries, the new schema improves performance by over 70%.

![](/uploads/clickstack_apr2026_image3_75d23f60fd.png)

Most of the query performance improvements occurred exactly where we expected them: text search, attribute filtering, and mixed search-and-filter workloads. Insert overhead remained broadly comparable to the previous schema, which was our primary concern going into the benchmarks.

Users looking to adopt the new schema should follow our [existing guide](https://clickhouse.com/docs/use-cases/observability/clickstack/performance_tuning#changing-the-primary-key) for modifying primary keys, as the same migration process applies here.

## Direct-read optimization for OpenTelemetry attribute maps {#direct-read-optimization-for-opentelemetry-attribute-maps}

A very common observability query pattern is filtering logs by attributes such as `http.status_code = 500` or `k8s.namespace.name = payments`.

In the default OpenTelemetry schema for ClickStack, these attributes live inside map columns such as `LogAttributes`, `ResourceAttributes`, and `ScopeAttributes`. Filters on these columns become queries like:

<pre><code type='click-ui' language='sql'>
LogAttributes['http.status_code'] = '500'
</code></pre>

or

<pre><code type='click-ui' language='sql'>
ResourceAttributes['k8s.namespace.name'] = 'payments'
</code></pre>

This flexible schema design is one of the reasons OpenTelemetry works well across heterogeneous workloads, but it also creates a challenge for query execution. ClickHouse needs an efficient way to determine which [granules](https://clickhouse.com/docs/guides/best-practices/sparse-primary-indexes#data-is-organized-into-granules-for-parallel-data-processing) may contain a given attribute key or value before reading and unpacking the underlying map data itself.

Earlier versions of the schema relied mostly on a bloom filter over map keys and values. This helped avoid unnecessary reads, but search-heavy attribute queries still meant more I/O and slower queries.

The new schema enables a new attribute-search path based on ClickHouse's text index. When enabled, values inside `ResourceAttributes`, `ScopeAttributes`, and `LogAttributes` are indexed using `text(tokenizer = 'array')`. This performs significantly better in our benchmarks for search-heavy attribute filtering workloads.

One complication here is that the query shape does not directly match the indexed expression. The index is built over `mapValues(LogAttributes)`, while the filter itself is expressed as a keyed map lookup. That still gives ClickHouse useful pruning information, but not enough to fully resolve the predicate from the index alone.

To avoid that mismatch, we added an alternate indexed representation for attribute maps. Each map is flattened into an array of `key=value` strings with a corresponding `text(tokenizer = 'array')` index.

<pre><code type='click-ui' language='sql'>
LogAttributes['http.status_code'] = '500'
</code></pre>

can be rewritten as:

<pre><code type='click-ui' language='sql'>
has(LogAttributeItems, 'http.status_code=500')
</code></pre>

This shape aligns exactly with the array tokenizer, allowing ClickHouse to evaluate the predicate from the index without unpacking the original map column. In our internal benchmarks, attribute filters that hit this path ran between 1.4 and 10 times faster than the equivalent map-subscript query.

![](/uploads/clickstack_apr2026_image4_3a6ff9ed6c.png)

*The green bar represents the performance of queries related to autocomplete for the previous implementation. The yellow bar represents the equivalent performance for the direct-read optimization.*

ClickStack now detects when a source has a compatible companion column for one of its OTel attribute maps and automatically rewrites matching attribute predicates. Users do not need to change their queries, and attributes still appear in the search bar as before.

For now, this optimization is opt-in rather than part of the default schema. The companion column currently needs to be declared as `MATERIALIZED` for the direct-read path to engage, which adds storage overhead. A ClickHouse fix allowing `ALIAS` columns to work the same way has already been merged and backported as far as 26.2. Once that ships, we expect to enable this feature by default without adding storage cost.

Users who want to enable the materialized path today can do so with a pair of `ALTER` statements per attribute map. The example below shows `ResourceAttributes`; the same pattern applies to `ScopeAttributes` and `LogAttributes`.

<pre><code type='click-ui' language='sql'>
ALTER TABLE otel_logs
  ADD COLUMN ResourceAttributeItems Array(String)
  MATERIALIZED arrayMap(
    (arr) -> concat(arr.1, '=', arr.2),
    CAST(ResourceAttributes, 'Array(Tuple(String, String))')
  )
  CODEC(ZSTD(1));

ALTER TABLE otel_logs
  ADD INDEX idx_res_attr_items ResourceAttributeItems
  TYPE text(tokenizer = 'array');
</code></pre>

Once the column and index exist, a Lucene query such as `ResourceAttributes.k8s.namespace.name:"payments"` is automatically translated by ClickStack into a `has(ResourceAttributeItems, 'k8s.namespace.name=payments')` predicate against the indexed companion column, rather than a map lookup against `ResourceAttributes` itself.

## Faster and richer autocomplete {#faster-and-richer-autocomplete}

Previously, autocomplete queried the live `otel_logs` and `otel_traces` tables directly to discover attribute keys and values. That approach was simple, but it scaled poorly once datasets became large enough that suggestion lookups started competing with normal query workloads.


autocomplete_v2.mp4

The new implementation moves autocomplete to materialized view rollups created alongside the primary OTel tables. Rather than scanning live observability data for suggestions, ClickStack now maintains compact metadata tables specifically for autocomplete lookups.

Each source table gets two materialized views — `{table}_kv_rollup_15m` stores key/value frequencies in fifteen-minute buckets, while `{table}_key_rollup_15m` stores aggregated key-level counts derived from the same data. The UI uses these tables directly for autocomplete suggestions and ranking.

Sources now expose a `metadataMaterializedViews` configuration describing the rollup tables and bucket interval.

<img src="/uploads/clickstack_apr2026_image5_372b43bb36.png" alt="" loading="lazy" style="max-width: 70%;">

During source discovery, ClickStack automatically checks for compatible rollups and wires them into autocomplete if available. The default Docker, Helm, and embedded deployments already create these views automatically.

The rollup combines all three OTel attribute maps alongside a handful of commonly queried native columns:

<pre><code type='click-ui' language='sql'>
CREATE MATERIALIZED VIEW IF NOT EXISTS otel_logs_attr_kv_rollup_15m_mv
TO otel_logs_kv_rollup_15m
AS WITH elements AS (
  SELECT 'ResourceAttributes' AS ColumnIdentifier,
         toStartOfFifteenMinutes(Timestamp) AS Timestamp,
         replaceRegexpAll(entry.1, '\[\d+\]', '[*]') AS Key,
         CAST(entry.2 AS String) AS Value
  FROM otel_logs ARRAY JOIN ResourceAttributes AS entry
  UNION ALL
  SELECT 'LogAttributes' AS ColumnIdentifier, ...
  FROM otel_logs ARRAY JOIN LogAttributes AS entry
  UNION ALL
  SELECT 'ScopeAttributes' AS ColumnIdentifier, ...
  FROM otel_logs ARRAY JOIN ScopeAttributes AS entry
  UNION ALL
  SELECT 'NativeColumn' AS ColumnIdentifier,
         toStartOfFifteenMinutes(Timestamp) AS Timestamp,
         'SeverityText' AS Key,
         CAST(SeverityText AS String) AS Value
  FROM otel_logs
  -- similar UNION ALL branches for ServiceName, ScopeName, etc.
)
SELECT Timestamp, ColumnIdentifier, Key, Value, count() AS count
FROM elements
GROUP BY Timestamp, ColumnIdentifier, Key, Value;
</code></pre>

These rollups mean autocomplete latency drops substantially on larger datasets. As an added bonus, suggestions are now frequency-ranked, which generally produces better defaults in the dropdown.

## Heatmaps as a first-class chart type {#heatmaps-as-a-first-class-chart-type}

Last month, we [shipped several improvements to Event Deltas](https://clickhouse.com/blog/whats-new-in-clickstack-march-2026#improvements-for-event-deltas), including always-on baseline distributions, proportional comparison scoring, filter and exclude actions from attribute comparison bars, and deterministic heatmap sampling. One limitation remained, though: the heatmap renderer was available only within the Event Deltas search workflow. If users wanted to visualize latency distributions elsewhere in the product, there was no way to reuse them.

In April, we moved the heatmap renderer into the shared charting system used by dashboards and the chart editor, allowing heatmaps to be available everywhere charts can be created.

From the chart editor, users select the Heatmap tab, define a `WHERE` clause and value expression, and the same distribution view previously limited to Event Deltas can now be added directly to dashboards.

![](/uploads/clickstack_apr2026_image6_bb7af03abf.png)

For Trace sources, ClickStack automatically initializes the chart with a duration expression and `count()` aggregation. The Y-axis also switches into duration formatting automatically, so labels render as milliseconds, seconds, or minutes instead of raw numeric values.

> To try this yourself, head to our [demo environment](https://play-clickstack.clickhouse.com) and add a heatmap tile to a dashboard against the OpenTelemetry demo dataset.

## Alerting improvements {#alerting-improvements}

Beyond SQL alerting, April also included several smaller alerting improvements requested by users. These changes are fairly incremental, but together they make the alerting workflow noticeably more flexible and less constrained by the editor itself.

### More threshold types {#more-threshold-types}

The threshold selector now supports the [full set of comparison operators](https://clickhouse.com/docs/use-cases/observability/clickstack/alerts): `>`, `≥`, `<`, `≤`, `=`, `≠`, alongside `BETWEEN` and `NOT BETWEEN` for range-based checks.

Equality and range operators also make a few common patterns easier to express directly, including heartbeat monitoring, fixed-capacity checks, and alerts that operate within an expected upper and lower bound.

Notification rendering was updated alongside the operator changes. Alert messages now describe the evaluated condition directly, rather than resorting to generic comparison wording. For example, a notification now reads "3 errors found, which equals the threshold of 3 errors" rather than the older "3 found, expected not equal to 3".

![](/uploads/clickstack_apr2026_image7_35075d95dc.png)

### Alert history and acknowledge in the editor {#alert-history-and-acknowledge-in-the-editor}

The alert editor now includes the same history and acknowledge/silence controls that previously only existed on the dedicated alerts page. Users can see when an alert last fired, inspect the value that triggered it, and silence or acknowledge the alert directly from the editor without switching views.

### Alert execution errors in the UI {#alert-execution-errors-in-the-ui}

Previously, if an alert query failed to compile or a webhook returned a non-2xx response, the alert would simply stop producing history entries. In many cases, there was no obvious indication in the UI that execution had failed at all.

The latest execution error is now persisted and surfaced in the alerts UI with an error indicator and expandable message details. This makes it possible to distinguish between an alert that simply has not fired recently and one that is actively failing to execute.

![](/uploads/clickstack_apr2026_image8_a509bebc50.png)

## Smaller things {#smaller-things}

A few smaller changes also landed this month that are less visible individually, but remove a surprising amount of friction from day-to-day use.

### Pie chart legend {#pie-chart-legend}

Pie charts now include a scrollable legend showing the slice color, label, and value for each segment. The legend is capped at 40% of the chart width to avoid overwhelming the chart, and it automatically scrolls once the number of slices exceeds the available space. Slice values also respect the chart's configured number formatting rules.

![](/uploads/clickstack_apr2026_image9_4583638af8.png)

### Per-series number formats {#per-series-number-formats}

Number formatting was previously configured at the chart level, meaning that every series in a line, bar, or table chart used the same units and suffixes. Series can now define their own `numberFormat` independently, while the chart-level format remains as a fallback.


per_series_format_v2.mp4

The change also carries through to the external dashboards API, so dashboards created or updated programmatically support the same per-series formatting behavior.

### Group-by columns on the left of tables {#group-by-columns-on-the-left-of-tables}

Table charts now support a display option that moves group-by columns to the left of the table, rather than rendering all series columns first. This is mainly useful for wider tables where grouping keys would otherwise end up pushed far off-screen behind a large number of metric columns.

The default layout remains unchanged, but users can now flip the ordering within each table to make the data easier to scan.


column_ordering.mp4

large_clickstack_apr2026_image1.png

medium_clickstack_apr2026_image1.png

small_clickstack_apr2026_image1.png

thumbnail_clickstack_apr2026_image1.png

clickstack_apr2026_image1.png

What's new in ClickStack - April 2026

Frustrated with how hard it is to navigate the OpenTelemetry Collector docs, we ended up building our own search-first interface just to get work done. It proved useful enough that we’ve decided to make it public.

[otel.fyi](https://otel.fyi) is a search-first site for OpenTelemetry Collector docs, making it easy to quickly find and understand configuration for receivers, processors, exporters, and extensions without digging through scattered documentation.

Summary

OpenTelemetry has become the standard for collecting and routing observability data. At the center of this ecosystem is the OpenTelemetry Collector, a vendor-neutral service that can be deployed in multiple roles across your architecture.

It can run as an agent, sitting close to your workloads to collect logs, traces, and metrics from applications, containers, and infrastructure. It can also operate as a gateway, receiving telemetry from many agents, processing and enriching that data, and routing it to one or more backends. This flexibility is what enables vendor interoperability and gives teams control over how data flows through their systems.

Unfortunately, the collector documentation can be hard to navigate in practice. 

Much of the Collector’s functionality lives in contrib packages. These are maintained separately from the core project, and their documentation typically exists in individual repositories as README.md files rather than in a single, unified site. The result is a fragmented experience where users are often forced to jump between folders, search with GitHub code search, and piece together configuration details manually.

## From internal frustration to a simple tool {#from_internal_frustration_to_a_simple_tool}

This challenge became hard to ignore. Mike, our Product lead for Observability, decided we needed something better. Not a replacement for the official docs, but a faster way to work with them.

Armed with his best friend Claude, he set about implementing what was, at its core, a fairly simple idea.

Take the existing documentation across the OpenTelemetry Collector ecosystem, extract the useful parts, and present them in a consistent, searchable format. Something optimized for how people actually configure the Collector day to day.

In practice, that meant parsing contrib repositories, pulling out configuration examples, and normalizing how receivers, processors, exporters, and extensions are presented. The goal was not completeness for its own sake, but usability. Reduce the time spent digging through README files and make the important details immediately accessible.

*> While the Collector docs aren’t ideal for human navigation, they’re highly structured under the hood, with consistent organization that makes extracting key metadata and configuration blocks straightforward.*

## A Search-First Experience for the Collector {#a_search_first_experience_for_the_collector}

The result is [**otel.fyi**](https://otel.fyi).

![otelfy_apr2026_image2.png](/uploads/otelfy_apr2026_image2_83b73fab1a.png)

It’s a simple site designed around one core workflow: finding the component you need, fast.

You can search across receivers, processors, exporters, and extensions, and immediately get a structured view of each. Instead of digging through long README files, you see the key information upfront, along with configuration examples pulled directly from the source.

Everything is normalized into a consistent format. No more guessing where a config block might be buried or how one component differs from another. The goal is to reduce the time from “I need to configure this” to “I have a working config.”

## Built for how people actually use OpenTelemetry {#built_for_how_people_actually_use_opentelemetry}

We built otel.fyi primarily for ourselves, because we needed something lightweight and fast, focused on the practical task of assembling Collector configurations without constantly jumping between repositories and README files, and as we started relying on it day to day, it became clear it could be useful beyond our own workflows.

Rather than keeping it internal, it made sense to make it available more broadly and see if it helps others working with OpenTelemetry in the same way.

## What’s next {#whats_next}

Search is just the starting point, and we’re already thinking about how to make this more useful in practice, including adding an AI assistant to help guide configuration, answer questions, and reduce the amount of context switching required when working with the Collector.

For now, the focus is simply on making the OpenTelemetry Collector easier to work with, based on the workflows we deal with every day.

We’ve found it genuinely useful in our own work, and if you’re spending time configuring OpenTelemetry, there’s a good chance you will too. Explore it at [otel.fyi](https://otel.fyi).


Interested in seeing how ClickHouse works on your data? Get started with ClickHouse Cloud in minutes and receive $300 in free credits.

 otel.fyi is a search-first site for OpenTelemetry Collector docs, making it easy to quickly find and understand configuration for receivers, processors, exporters, and extensions without digging through scattered documentation.

large_otelfy_apr2026_image1.png

medium_otelfy_apr2026_image1.png

small_otelfy_apr2026_image1.png

thumbnail_otelfy_apr2026_image1.png

otelfy_apr2026_image1.png

otel.fyi - OTel Collector docs made simple

Welcome to the March edition of What's New in ClickStack.

Each month, we share the latest updates across ClickStack, from platform enhancements to new features designed to make observability faster, simpler, and more powerful. March brings a broad set of improvements: deeper event analysis with always-on Event Deltas and smarter attribute scoring, a complete expansion of SQL chart types with support for Grafana-style template macros as well as import/export support, correct aggregations over sampled trace data, persistent dashboards for those of you running in local mode, and a collection of dashboard organisation improvements.

A big thank you to our open source contributors, as well as to our users whose feedback helps shape these features and make ClickStack better for everyone.

## New contributors

As always, a huge thank you to our open source contributors, including those who jumped in for the first time this month to help improve ClickStack for everyone.

[ZeynelKoca](https://github.com/ZeynelKoca) [sanjams2](https://github.com/sanjams2) [vinzee](https://github.com/vinzee) [vinzee](https://github.com/vinzee)[sanjams2](https://github.com/sanjams2) [ZeynelKoca](https://github.com/ZeynelKoca) [matsilva](https://github.com/matsilva)

If code contributions are not your thing, we welcome documentation improvements, ideas, feature suggestions, bug reports, and general feedback via the [repository](https://github.com/hyperdxio/hyperdx). Every contribution, big or small, helps make the stack better for the entire community.

## AI notebooks

Earlier in the month, we announced AI Notebooks, a new way to investigate logs, metrics, and traces with AI embedded directly into a structured, notebook-style workspace. This represents our first step toward a native, agentic experience inside ClickStack, where AI acts as a collaborator within the SRE workflow rather than a separate interface. Investigations unfold step by step, combining natural language, generated queries, and manual analysis, while keeping engineers firmly in control.



notebooks_short_hd.mp4

AI Notebooks are currently available in private preview for Managed ClickStack, and we’re working closely with early users to refine the experience. We’d welcome feedback as we continue to evolve this direction. You can learn more in the[ announcement post](https://clickhouse.com/blog/clickstack-ai-notebooks) or request [access via the waitlist](https://clickhouse.com/cloud/ai-notebooks-in-clickstack-waitlist).

## Improvements for Event Deltas

Event Deltas is one of the most powerful tools in ClickStack for root cause analysis. Given a heatmap of slow or erroring spans, it surfaces which attribute values appear disproportionately in a selected region compared to the background. This is critical for SREs and developers investigating production issues, allowing them to quickly identify the attributes and correlated span characteristics driving performance degradation or errors. Instead of manually slicing data or forming complex queries, Event Deltas highlights the signals that matter, accelerating the path from symptom to root cause. For a deeper dive into how the feature works, see our [dedicated blog post](/blog/faster-root-cause-for-slow-traces-with-clickstack-event-deltas).

This month, we made four significant improvements across how the feature behaves.

> To play with these changes, we recommend heading over to our [demo environment ](https://play-clickstack.clickhouse.com/search?source=3b743139&where=&select=&whereLanguage=lucene&filters=%255B%255D&orderBy=&mode=delta&isLive=false&from=1775654690000&to=1775741090000&xMin=1775666834.0190363&xMax=1775719838.3538175&yMin=1.7378845061203285&yMax=913.6388954631163)where you can experiment with Event Deltas on the [OpenTelemetry demo dataset](https://clickhouse.com/docs/use-cases/observability/clickstack/getting-started/remote-demo-data) yourself.

### Always-on attribute distribution

Previously, the attribute distribution charts were only populated after you selected an area on the heatmap to compare that selection against the background spans. Now, the view immediately shows the attribute and value distribution for all spans in the current time window (represented by blue "All spans" bars). This allows you to immediately spot dominant behaviors across the dataset without needing to make a selection first - even when the heatmap is stable and shows no obvious changes. 

When a user selects a region, the chart switches to comparison mode, showing red and green bars contrasting the selected group against the overall distribution. This feature is valuable for general data exploration and when you are investigating a specific hypothesis (e.g., focusing on spans with a certain status code or looking only at client calls to SQL).

> Although a small change on the surface, this feature has the potential to unlock entirely new workflows. We’ll follow up with a dedicated blog post exploring our vision for it and how we think can simplify investigative workflows in ClickStack.

![event_deltas_no_selection.png](/uploads/event_deltas_no_selection_fb3d54050a.png)

When you click and drag to select a region, the chart transitions to comparison mode and shows red and green bars contrasting the selected group against the background. 

![event_deltas_selection.png](/uploads/event_deltas_selection_36818f5a3f.png)

### Smarter attribute sorting

Ranking attributes by diagnostic usefulness is harder than it looks. The previous implementation sorted by maximum raw delta, which produced misleading rankings when the outlier and inlier groups had different sample sizes. An attribute with identical distribution in both groups could still rank highly if the raw counts differed.

For example, imagine `service.name = checkout` appears 1,000 times in the background and 100 times in the selected region, while `service.name = payments` appears 10 times in the background and 8 times in the selected region. Despite both having very similar proportional distributions, the raw delta for checkout is much larger, causing it to rank higher even though it is not more indicative of the issue. In practice, this meant attributes with high absolute counts were often prioritised over those that were actually more strongly correlated with the anomaly.

Instead, we now use proportional comparison scoring, which normalises each group's percentages to sum to 100% before computing the delta. Attributes with identical proportional distributions score zero regardless of how the raw counts differ, making the ranking far more reliable when groups are unequal in size.

### Filter, exclude, and copy from attribute bars

The real value of Event Deltas is not just identifying outliers, but explaining why they differ from normal behavior. By comparing a selected subset of spans, the foreground or outliers, against the baseline distribution, the background or inliers, it surfaces which attribute values are disproportionately associated with degraded performance. This removes the need for the manual, iterative workflow of filtering, grouping, and visually comparing distributions across columns. 

However, historically, once users identified a suspicious attribute, the next step was still a little cumbersome. Translating that insight into a concrete query, validating it, and continuing the investigation required multiple manual steps.

To address this, clicking any bar in the attribute comparison chart now opens an action popover with three options: include the value, exclude it, or copy it to the clipboard.

![event_deltas_filtering.png](/uploads/event_deltas_filtering_18ad04cea0.png)

This allows users to immediately act on what Event Deltas reveals. For example, above a subset of slow spans shows that 93 percent of outliers involve `card_type = Visa`, while the background is dominated by other card types, this strongly suggests a Visa-specific issue. Including the value lets users isolate and inspect only those problematic spans to confirm the hypothesis. Excluding it helps verify whether performance returns to normal without that factor, or reveals secondary outliers that were previously masked.  

### Deterministic sampling

Event Deltas samples spans when building the heatmap. Previously this used `ORDER BY rand()`, which meant hovering over the same region across two renders could highlight different cells, making the interface feel unstable. Sampling now uses `ORDER BY cityHash64(SpanId)`, so the same query always selects the same subset of spans and the heatmap behaves consistently across interactions - important to ensure analysis is repeatable.

## SQL charts with Grafana-style macros

Query builders are great for getting started and covering the common path, but they are inherently opinionated. As queries become more complex, joining across datasets, applying custom aggregations, or expressing nuanced logic, users often need direct access to SQL to fully exploit the underlying power of ClickHouse. Supporting this balance between simplicity and flexibility has been a key focus for ClickStack.

Over the past several months, we have been steadily expanding support for raw SQL charts across all visualisation types. This month, we completed the last two chart types and significantly deepened the feature set for users writing SQL directly.

Raw SQL is now available for number tiles, pie charts, line charts, table charts, and stacked bar charts - expanding on support for tables last month. Users writing their own queries can now use the full expressiveness of ClickHouse to drive any visualisation, not just the ones the query builder supports.

![sql-charts.png](/uploads/sql_charts_0dc33889ab.png)

SQL charts bring a high degree of flexibility, allowing users to express complex queries beyond the constraints of the query builder. At the same time, they still need to integrate seamlessly with the rest of the dashboard experience, particularly respecting global filters and time ranges. Without this, SQL charts quickly become disconnected from the surrounding context.

To address this, we have introduced a set of template macros that expand at query time, following conventions familiar to Grafana users. These allow users to write expressive SQL while automatically inheriting the dashboard’s current time window and active filters, ensuring consistency across all visualisations.

`$__timeFilter(column)` expands to a seconds-precision range predicate on the named column. `$__timeFilter_ms(column)` does the same at millisecond precision. `$__timeInterval(column)` produces a `toStartOfInterval` expression for use in a `GROUP BY`, automatically aligned to the selected time window granularity.

`$__filters` is replaced at query time with the active dashboard filter predicates. When no filters are active, it expands to `1=1` so the query remains valid without any conditional logic. A source must be selected on the chart for filter introspection to work.

A typical raw SQL chart using these macros might look like this:


The macro `$__sourceTable` resolves to the fully qualified table name of the selected source at query time. This is particularly useful for import and export workflows. When a dashboard containing raw SQL charts is exported and imported into a different environment, the source mapping applied during import is automatically substituted into the macro. There is no need to manually update table references after importing.

> The macro also accepts a metric-type argument: `$__sourceTable(sum)` resolves to the appropriate metric table for sum-type aggregations, which is necessary when querying OpenTelemetry metric tables which are partitioned by aggregation type.

Raw SQL charts are also now fully supported in the external API across all five display types: line, number, pie, table, and stacked bar. Teams managing dashboards programmatically through the API can now create and update SQL-backed tiles using the same endpoints used for builder-based charts.

## Aggregations for sampled trace data

As observability datasets grow, many high-throughput systems turn to sampling to control storage and ingestion costs. Both head-based and tail-based sampling follow the same principle: retain only a subset of spans while discarding the rest. Head sampling makes decisions early, often probabilistically or via simple rules, while tail sampling evaluates full traces before deciding what to keep. Although these approaches differ in execution, they share a common outcome: the stored dataset is no longer complete.

In ClickHouse, sampling is often unnecessary for many workloads due to high compression and strong query performance at scale. However, at very large volumes, some users still choose to sample. The challenge is that once data is sampled, standard aggregations become incorrect. Counts underestimate true volume, averages become biased toward retained spans, and percentiles no longer reflect the full distribution. In short, you lose statistical accuracy unless the sampling is accounted for during query execution.

To address this, ClickStack introduces sample-aware aggregations at the source level. Since sampling is a property of the dataset, we allow users to define how to interpret it directly in the trace source configuration. This is done via a sampleRateExpression, which evaluates to the per-span sampling rate, typically stored alongside each span, for example `SpanAttributes['SampleRate']`. This allows sampling rates to vary across spans while still being handled consistently.

![sampling_config.png](/uploads/sampling_config_dd92ff26b3.png)

Once configured, ClickStack automatically rewrites aggregations to account for sampling. A count() becomes `sum(weight)`, where the weight represents the inverse sampling rate. Averages are computed as weighted averages with null-safe division, sums are scaled accordingly, and percentile calculations use quantileTDigestWeighted to preserve distribution accuracy. The weight itself is computed as `greatest(toUInt64OrZero(toString(expr)), 1)`, ensuring that missing or invalid sampling rates default safely.

This correction is applied transparently across dashboards, alerts, the external API, and AI-powered summarisation. By defining sampling once at the source level, users can continue to build charts and queries as usual, with ClickStack ensuring the results remain statistically correct.

![sampled_chart.png](/uploads/sampled_chart_b48837ebf0.png)

_A simple count on a sampled dataset maps to a sum on the sample rate - `sum(greatest(toUInt64OrZero(toString(SpanAttributes['SampleRate'])), 1))`_

## Dashboard template gallery and listing pages

As ClickStack usage grows, so does the number of dashboards teams create. Previously, dashboards were surfaced primarily through the sidebar, which worked well for smaller setups but became harder to navigate at scale. Users often struggled to discover what already existed, organise dashboards effectively, or get started without building everything from scratch.

To address this, we introduced dedicated listing pages for dashboards and saved searches. These provide a clear, searchable view of all resources, replacing the previous flat sidebar model. From these pages, users can filter by name. 

![dashboard_listing.png](/uploads/dashboard_listing_2336565a0a.png)

The interaction pattern is consistent across dashboards and saved searches, and the sidebar now links directly to these views, giving users a more scalable way to manage and navigate their observability assets.

![saved_search.png](/uploads/saved_search_5e446f1a57.png)

Building on this, we introduced a template gallery to help users get started faster. The gallery provides a curated set of pre-built, importable dashboards for common runtime environments. The initial set covers OpenTelemetry runtime metrics for JVM, .NET, Go, and Node.js. These templates offer an immediate starting point, allowing users to visualise key metrics without needing to construct dashboards from scratch. Each template is ready to use with any service instrumented via the OpenTelemetry SDK, requiring only a source selection during import. Templates are grouped by tag, making them easy to browse and discover.

![dashboard_template.png](/uploads/dashboard_template_d9122f0eea.png)

## Favorites for dashboards and saved searches

Building on the new listing pages, we have also made it easier to prioritise and quickly access the dashboards and saved searches that matter most.

Dashboards and saved searches can now be marked as favorites. Favorited items float to the top of their respective listing pages and are pinned in the sidebar for immediate access. Favorites are stored per user, so each team member maintains their own independently.

## Dashboard filter improvements

Last year, we introduced [dashboard filters](https://clickhouse.com/blog/whats-new-in-clickstack-october-2025#dashboard-filtering) to provide a simple way to apply global filtering across all charts in a dashboard. This removed the need to duplicate filter logic across individual queries and made dashboards significantly easier to configure and reuse.

This month, we’ve made two targeted improvements to make filters more flexible and performant.

Filters can now include an optional `WHERE` condition that restricts which rows are scanned when populating available filter values. This is particularly useful for high-cardinality fields or columns that exist across large datasets. By limiting the scope of the lookup query to a relevant subset, filter drop downs remain fast and responsive even at scale. This applies to both user-defined and preset filters.





dashboard_filters.mp4

Filters now also support selecting multiple values. These are applied as an `IN` clause, for example `toString(environment) IN ('production', 'staging')`. Previously, filters were limited to a single value, making it cumbersome to compare environments, regions, or services within the same dashboard. This change makes dashboards far more flexible for side-by-side analysis.

## localStorage for dashboards and saved searches in local mode 

ClickStack can run in local mode, where the UI connects directly to ClickHouse from the browser without a backend API. This mode powers the embedded deployment inside the ClickHouse binary, announced [last month](https://clickhouse.com/blog/clickstack-embedded-clickhouse), and is also used by developers who want the simplest possible self-hosted setup.

Until this month, local mode had no way to persist dashboards or saved searches across page reloads. We have added a `createEntityStore` abstraction that backs all dashboard and saved search operations with browser localStorage when local mode is active. Users can now create, edit, and save dashboards and searches that persist across sessions, with no server or database required. The new favorites feature, describe above, use the same mechanism.

## More chart display units

Charts now support a much broader range of display units, making it easier to present metrics clearly without relying on titles or aliases for context.

This release significantly expands unit coverage across data sizes, data rates, and throughput. It includes full support for both IEC and SI standards for bytes and bits, with scales ranging from kilobytes through petabytes, along with their per-second equivalents. Throughput units have also been extended to cover common operational metrics such as requests, operations, reads, writes, and IOPS, with both per-second and per-minute variants.

![new_metrics.png](/uploads/new_metrics_c4e0e4f0ef.png)

Existing formats like number, currency, percentage, and time remain available under a unified “Basic” group, with time continuing to support granular units down to microseconds and nanoseconds.



ClickStack’s March release introduces smarter Event Deltas, AI-powered notebooks, and full SQL chart flexibility, making investigation faster and dashboards more powerful.

large_whats-new-clickstack-march.png

medium_whats-new-clickstack-march.png

small_whats-new-clickstack-march.png

thumbnail_whats-new-clickstack-march.png

whats-new-clickstack-march.png

What's new in ClickStack - March 2026

## We taught ClickStack to read your logs like a detective novel

If you've ever been paged at 3am and stared at a wall of `EmptyCartAsync called with userId=a0cd950c-39ec-11f0-8ddd-a2eca416a8a4` wondering what it means for the business -- you're not alone.

Logs are written by machines, for machines. Traces are trees of span with nanosecond timestamps. Log patterns are clusters of identical messages that tell you *something* is happening 113,526 times but won't tell you *why you should care*. The gap between raw telemetry and human understanding is where SRE time goes to die.

Today we're shipping **AI Summarize** -- a new feature in HyperDX that generates narrative summaries of your logs, traces, and log patterns. It works on any event in the side panel and on the pattern drawer. One click, and your cryptic span becomes a story.

## What It Looks Like

Open any log entry, trace span, or log pattern in HyperDX. You'll see a new **Summarize** button below the event body. Click it, and after a brief analysis you get something like this:

![april_fools_ai_clickstack_1.png](/uploads/april_fools_ai_clickstack_1_112d4f71ce.png)

Or maybe you'll get David Attenborough narrating your checkout flow:

![april_fools_ai_clickstack_2.png](/uploads/april_fools_ai_clickstack_2_2b7d270393.png)

Or Shakespeare lamenting your latency:

![april_fools_ai_clickstack_3.png](/uploads/april_fools_ai_clickstack_3_01357825e5.png)

Hit **Regenerate** to get a new version. The theme adapts to context -- errors get Detective Noir, performance issues get Shakespearean Drama, and normal info events get the Nature Documentary treatment.

## It knows your stack

The summaries aren't random mad-libs. AI Summarize understands the OpenTelemetry and Kubernetes attributes already present in your telemetry -- service names, versions, HTTP endpoints, database systems, RPC calls, exceptions, pod names, namespaces, durations, and more. It reads what's there and weaves it into the narrative.

A 1ms Redis call gets *"extraordinarily swift -- the peregrine falcon of API calls, diving at breathtaking speed."* A checkout span that errors out with a cache exception gets *"Then I found the body -- the kind of exception that ends careers and starts postmortems."* A 5-second database query gets *"an age! Methinks the user doth grow weary, staring at the spinning wheel of fortune."*

The mood adapts too. Errors and exceptions trigger darker themes. Warnings get suspicious. Healthy spans get the nature documentary they deserve.

For **log patterns**, the summary incorporates the repeat count -- because a message that appears 113,526 times deserves to be called out:

*"Hark! A refrain most persistent: 'EmptyCartAsync called with &lt;*>'. 113,526 times it echoes through the cluster, like a chorus that hath forgotten how to stop."*

## Zero tokens. Zero data sharing. Zero cost.

Here's the part we're most proud of: **AI Summarize doesn't use any LLM.** There is no API call to OpenAI, Anthropic, or any other provider. No tokens are consumed. Your data never leaves the browser.

The summaries are generated entirely on the client side using hand-written phrase pools and OTel-aware data extraction. The "AI" in "AI Summarize" stands for "Artisanally Improvised."

This means:

* **No cost** -- works on every HyperDX deployment, open source or cloud, with no AI API key required
* **No privacy concerns** -- event data stays in your browser tab, never sent to a third-party model
* **No latency** -- the ~2 second "analysis" delay is theatrical, not computational
* **No hallucinations** -- every fact in the summary comes directly from your event attributes

Click the `(i)` icon next to any summary to see the disclosure. If the feature isn't for you, the same popover has a "Don't show again" link that persists via localStorage.

## Try it

**AI Summarize** is going live today in HyperDX. Open any log, trace, or pattern and look for the sparkle icon.

After the first week the button is hidden by default to keep the UI clean, but you can bring it back anytime by adding `?smart=true` to your HyperDX URL. It stays active through the end of April 2026.

We're also evaluating a version that uses actual AI on the backend -- the infrastructure is already in place. If you'd like to see real LLM-powered summaries as a permanent feature, let us know on [GitHub](https://github.com/hyperdxio/hyperdx) in [Slack](https://clickhousedb.slack.com/archives/C09GJFL66FK).

Happy April Fools! The joke is the delivery, not the feature. Every fact in the summary comes from your real OTel attributes. Every Kubernetes pod name is accurate. We just thought your 3am pages deserved better writing.

*"We are such stuff as spans are made on, and our little traces are rounded with a timeout."*


ClickStack gets a literary upgrade with "AI Summarize", transforming raw logs into vivid, story-driven narratives that finally explain what's really happening in your systems.

large_clickstack_april_fools.png

medium_clickstack_april_fools.png

small_clickstack_april_fools.png

thumbnail_clickstack_april_fools.png

clickstack_april_fools.png

We taught ClickStack to read your logs like a detective novel

Welcome to the February edition of What’s New in ClickStack.

Each month, we share the latest updates across ClickStack, from platform enhancements to new features designed to make observability faster, simpler, and more powerful. February brings major improvements to both Cloud and open source, including new query workflows, enhanced metrics exploration, performance optimizations, and expanded alerting options.

A big thank you to our open source contributors, as well as to our users whose feedback helps shape these features and make ClickStack better for everyone.

## New contributors {#new-contributors}

As always, a huge thank you to our open source contributors, including those who jumped in for the first time this month to help improve ClickStack for everyone.

[AdityaPimpalkar](https://github.com/AdityaPimpalkar) [Rajin9601](https://github.com/Rajin9601)[mlsalcedo](https://github.com/mlsalcedo) [themavik](https://github.com/themavik) [Misfits09](https://github.com/Misfits09) [Bre77](https://github.com/Bre77) [alex-clickhouse](https://github.com/alex-clickhouse) [adri](https://github.com/adri) [mxmCherry](https://github.com/mxmCherry) 

If code contributions are not your thing, we welcome documentation improvements, ideas, feature suggestions, bug reports, and general feedback. Every contribution, big or small, helps make the stack better for the entire community.


## External API for ClickHouse Cloud {#external-api-for-clickhouse-cloud}

For many teams, configuration as code is a hard requirement. The [ClickStack API](https://clickhouse.com/docs/use-cases/observability/clickstack/api-reference) has been available in open source for some time, and it has quickly become essential for enterprises that need to manage dashboards and alerts at any scale. This month, we are excited to bring that same capability to ClickHouse Cloud.

With ClickStack resources now available in the ClickHouse Cloud OpenAPI, you can manage dashboards, alerts, sources, and webhooks directly through the Cloud API. Observability configuration can live alongside your application code, flow through CI and CD pipelines, and remain consistent across development, staging, and production environments.

For example, listing all dashboards for a service is now as simple as:

<pre><code type='click-ui' language='bash'>
curl -X GET \
  'https://api.clickhouse.cloud/v1/organizations/{organizationId}/services/{serviceId}/clickstack/dashboards' \
  --user '&lt;keyId&gt;:&lt;keySecret&gt;' \
  -H 'Content-Type: application/json'
</code></pre>

No separate credentials are required. Existing ClickHouse Cloud API keys with the appropriate permissions work out of the box.

This is the first step toward fully automated, production-grade observability workflows in ClickStack. We continue to expand resource coverage and Terraform support is planned. For full details and examples, see the [dedicated announcement](https://clickhouse.com/blog/clickstack-api) and [API reference](https://clickhouse.com/docs/use-cases/observability/clickstack/api-reference).

## ClickStack embedded in ClickHouse {#clickstack-embedded-in-clickhouse}

This month, we made getting started with ClickStack easier than ever. With ClickHouse 26.2, the ClickStack UI is embedded directly in the ClickHouse binary. Download ClickHouse or start a Docker container, open http://localhost:8123/clickstack, and you are ready to explore.

<iframe width="768" height="432" src="https://www.youtube.com/embed/s1MGNcVNvNg?si=KpqkwsVHtU_-1py-" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

This embedded version is designed for local development, learning, and experimentation. It gives you a simple way to visualize your own observability data or even inspect ClickHouse itself using its internal logs and system tables. 

![](/uploads/clickstack_feb2026_image1_3ef1e34fb9.png)

While it is not intended for production deployments, it is a powerful way to understand query performance, diagnose local issues, and explore how your instance behaves, all from a built-in UI that ships with ClickHouse out of the box.

If you are curious how we package the UI directly into the ClickHouse binary without significantly increasing its size, adding only around 4.1 MB, while integrating cleanly into the ClickHouse build system, we recommend reading the full [announcement blog post](https://clickhouse.com/blog/clickstack-embedded-clickhouse).

## Raw SQL tables {#raw-sql-tables}

One of the most consistent pieces of feedback we hear is simple: “I just want to write SQL and chart it.”

From day one, ClickStack has focused on making visualizations easy to build. Line and bar chart builders, number tiles, pie charts (see below), search views, markdown, and guided workflows are all designed to help users create powerful dashboards without needing to write SQL. But every wizard has limits. Simplification makes common tasks fast, yet it can also hide some of the underlying power.

Because ClickStack is powered by ClickHouse, it sits on top of a fully featured, SQL compliant engine with a rich set of [analytical and aggregation functions](https://clickhouse.com/docs/sql-reference/aggregate-functions). That flexibility is one of its biggest strengths. Over the coming months, we will begin exposing native SQL across visualization types, giving users the choice between the builder for convenience and raw SQL for full control.

We are starting with tables. In the table visualization, users can now switch between the default Builder mode and a new SQL mode. From there, you can write a native SQL query directly, including referencing built-in time range parameters for start and end timestamps. 

<blockquote>
<p style="font-size: 15px">
When the chart is added to a dashboard, the time variables are automatically injected, so your query stays dynamic and aligned with the selected time window.
</p>
</blockquote>

This unlocks far more than simply writing longer or more complex queries than the table builder allows. The builder is intentionally opinionated. For tables, it focuses on grouping by a column and calculating metrics across the remaining fields. That works well for common workflows, but it cannot express more advanced analytical patterns.

With raw SQL, users can now join across datasets, correlate signals, and compute derived metrics that span multiple tables. For example, you might join logs to traces to compare total log volume, error counts, and average latency in a single result set.

<pre><code type='click-ui' language='sql'>
WITH
  Traces AS (
    SELECT
      ServiceName,
      avg(Duration) AS avg_duration,
      quantile(0.99)(Duration) AS p99_duration
    FROM otel_v2.otel_traces
    WHERE
      Timestamp >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64})
      AND Timestamp < fromUnixTimestamp64Milli({endDateMilliseconds:Int64})
    GROUP BY ServiceName
  ),
  Errors AS (
    SELECT
      ServiceName,
      countIf(SeverityText = 'error') AS error_log_count
    FROM otel_v2.otel_logs
    WHERE
      TimestampTime >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64})
      AND TimestampTime <= fromUnixTimestamp64Milli({endDateMilliseconds:Int64})
      AND SeverityText = 'error'
    GROUP BY ServiceName
  )
SELECT
  coalesce(Traces.ServiceName, Errors.ServiceName) AS ServiceName,
  avg_duration,
  p99_duration,
  error_log_count
FROM Traces
FULL OUTER JOIN Errors
  ON Traces.ServiceName = Errors.ServiceName
ORDER BY ServiceName
LIMIT 200;
</code></pre>

![](/uploads/clickstack_feb2026_image4_27bbe951f5.png)

<blockquote>
<p style="font-size: 15px">
In raw SQL mode, users select just a connection. There's no need to specify a data source, unlike the Query Builder, with users free to query across multiple data sources at once.
</p>
</blockquote>

Or consider a lightweight service map style view. A self JOIN on spans can show request counts between service pairs, total errors, and percentage error rates (also available visually within [our service map feature](https://clickhouse.com/blog/whats-new-in-clickstack-november-2025#service-maps)). This kind of relationship analysis would be extremely difficult to model coherently in a visual builder, but is straightforward in SQL:

<pre><code type='click-ui' language='sql'>
WITH
  ServerSpans AS (
    SELECT TraceId AS traceId,
           SpanId AS spanId,
           ServiceName AS serviceName,
           ParentSpanId AS parentSpanId,
           StatusCode AS statusCode
    FROM otel_v2.otel_traces
    WHERE SpanKind IN ('Server', 'Consumer', 'SPAN_KIND_SERVER', 'SPAN_KIND_CONSUMER') AND
     Timestamp >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64})
      AND Timestamp < fromUnixTimestamp64Milli({endDateMilliseconds:Int64})
  ),
  ClientSpans AS (
    SELECT TraceId AS traceId,
           SpanId AS spanId,
           ServiceName AS serviceName,
           ParentSpanId AS parentSpanId,
           StatusCode AS statusCode
    FROM otel_v2.otel_traces
    WHERE SpanKind IN ('Client', 'Producer', 'SPAN_KIND_CLIENT', 'SPAN_KIND_PRODUCER') AND 
    Timestamp >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64})
      AND Timestamp <= fromUnixTimestamp64Milli({endDateMilliseconds:Int64})
  )
SELECT
  ServerSpans.serviceName AS serverServiceName,
  ClientSpans.serviceName AS clientServiceName,
  count(*) * 10 AS requestCount,
  countIf(ServerSpans.statusCode = 'Error') AS error_count,
  round(error_count / requestCount, 3) AS `% error count`
FROM ServerSpans
LEFT JOIN ClientSpans
  ON ServerSpans.traceId = ClientSpans.traceId
  AND ServerSpans.parentSpanId = ClientSpans.spanId
WHERE ClientSpans.serviceName IS NULL
   OR ServerSpans.serviceName != ClientSpans.serviceName
GROUP BY serverServiceName, clientServiceName
ORDER BY serverServiceName, clientServiceName;
</code></pre>

![](/uploads/clickstack_feb2026_image6_5a88b2c3c7.png)

This is the first step toward combining the simplicity of guided builders with the full expressiveness of SQL, giving advanced users the freedom to unlock everything ClickHouse can do. Stay tuned over the following months to see SQL being exposed in other visualizations.

## Metric Attribute Explorer {#metric-attribute-explorer}

ClickStack has long supported OpenTelemetry metrics (similar to Prometheus in concept), stored as separate tables per data type, such as gauges and counters. While this model is flexible and powerful, discovering how to work with metrics and their associated labels has often required a degree of trial and error.

In this release, we have made metric discovery more intuitive. Users typically know which metric they want to plot and can select it using autocomplete as before. Now, once a metric is selected, they can expand an associated attributes panel that displays the labels available for that specific metric. Instead of guessing which labels exist, users can immediately see and select them.


metrics_explorer.mp4


In the example above, we first plot an average of the `k8s.pod.memory.working_set (Gauge)` metric. We're immediately told this has 44 associated attributes. We expand the attributes panel and select the `k8s.deployment.name` label. From there, the label can either be applied as a filter to narrow the chart or added as a group to break the metric down by Kubernetes deployment. In this case, we group by deployment to compare working set size across services.

This streamlined flow removes much of the guesswork from metrics exploration. Users no longer need to manually experiment to discover which labels are available for grouping or filtering. Charting OpenTelemetry metrics becomes a more direct, visual process, focused on insight rather than label discovery.

## Pie charts {#pie-charts}

One of the most frequent requests we receive is for a broader set of visualization types. Expanding charting capabilities has been on our backlog for some time, and over the coming months we will continue closing those gaps, prioritizing the visualizations users ask for most.

Pie charts are one of the more [controversial chart types in analytics](https://www.ataccama.com/blog/why-pie-charts-are-evil), yet they remain a popular choice in observability. While they are not suited to every scenario, they can still be effective for showing proportional breakdowns, such as status codes, error categories, or request distribution across services.

Pie charts are now available in the latest version of ClickStack. To build one, users simply select a metric to define the slice size and then choose a group by field to determine how the slices are segmented. The distinct values of that field form each slice of the chart. As with other visualizations, filters can be applied to narrow the dataset before rendering.

![](/uploads/clickstack_feb2026_image3_c4dfca64e0.png)

Pie charts are supported across traces, logs, and OpenTelemetry metrics, and they benefit from the same [accelerated materialized view support](https://clickhouse.com/docs/use-cases/observability/clickstack/materialized_views) introduced earlier this year. This ensures that even high-volume breakdowns remain responsive and performant.

## Settings for even faster querying {#settings-for-even-faster-querying}

We are constantly looking for ways to improve query performance in ClickStack. Sometimes that means leveraging the [right access patterns](https://clickhouse.com/blog/whats-new-in-clickstack-september-2025#chunking-time-windows) or ensuring users can [exploit features such as materialized views](https://clickhouse.com/docs/use-cases/observability/clickstack/materialized_views). Often, however, it just comes down to ensuring the correct query settings and optimizations are applied when appropriate.

The ClickHouse core team ships performance improvements and new optimizations in every release. Tracking these changes and ensuring ClickStack takes advantage of them is an ongoing priority. Recent updates in ClickHouse have unlocked meaningful performance gains, and we now enable several of these optimizations when appropriate and when they are supported by the underlying ClickHouse version.

The following optimizations are now automatically applied where appropriate.

### Top N Queries {#top-n-queries}

Top N queries are everywhere in observability. “Show me the latest logs.” “Give me the top error messages.” “List the slowest requests.” These patterns typically look like `ORDER BY … LIMIT N`, and they are especially common in log search and ranking-style dashboards.

ClickHouse has recently introduced powerful optimizations that treat Top-N as a first-class query pattern. In 25.12, support for skip-index-driven Top-K filtering was added via the `use_skip_indexes_for_top_k` setting. This allows ClickHouse to use min/max metadata from data skipping indexes to eliminate entire granules before any rows are read. Instead of scanning a full table and then sorting, the engine can prune large portions of data up front. In benchmarks for ClickStack, this has delivered 2x to 3x improvements for typical log search style queries, and in some cases much more.

<iframe width="768" height="432" src="https://www.youtube.com/embed/SyayPSrsAhI?si=bfzOoxai7rGHPZqB" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

ClickStack now enables `use_skip_indexes_for_top_k = 1` by default when supported, along with `query_plan_max_limit_for_top_k_optimization` (set to `100000`) to allow the optimization to kick in for sufficiently large result scans. When the `ORDER BY` aligns with the table’s ordering key, pruning is highly effective because granules can be skipped purely based on metadata.

<blockquote>
<p style="font-size: 15px">
When the sort column is not part of the ordering key, ClickHouse can still apply a dynamic Top-N threshold during execution, skipping granules that cannot improve the result set via <code>use_top_k_dynamic_filtering = 1</code>, delivering up to 2x improvements in some real-world log searches depending on data distribution and predicates; however, this is <strong>not yet enabled</strong> globally in ClickStack because features such as Event Patterns rely on functions like <code>rand()</code> that are incompatible with the optimization. We plan to enable it selectively in the near future.
</p>
</blockquote>

These settings turn many Top-N queries into a metadata pruning problem rather than a full table scan. As datasets grow and cold cache scenarios become more common, avoiding unnecessary reads at the granule level becomes increasingly impactful, and ClickStack now takes advantage of this automatically.

For a deep dive on these features, we recommend our [dedicated blog post.](https://clickhouse.com/blog/clickhouse-top-n-queries-granule-level-data-skipping)

### Faster skip indices {#faster-skip-indices}

ClickStack already relies heavily on ClickHouse [data skipping indexes](https://clickhouse.com/docs/optimize/skipping-indexes/examples) to accelerate common observability workloads. Bloom filter indexes power fast text search across logs. Minmax indexes are widely used to accelerate numeric range queries, especially on timestamps and other high cardinality fields. Users are [encouraged to exploit these indices](https://clickhouse.com/docs/use-cases/observability/clickstack/performance_tuning#adding-skip-indices) if they need to perform schema optimization.

Before ClickHouse 25.9, skip indexes such as minmax, set, bloom filter, vector, and more [recently text](https://clickhouse.com/blog/full-text-search-ga-release) were evaluated up front, before any table data was read. This sequential approach had a few important drawbacks. Queries with LIMIT still had to scan the entire index before execution could begin. There was an initial startup delay while index analysis completed. In some cases, scanning the index itself could cost more than processing the data.

ClickHouse 25.9 introduced streaming evaluation of secondary indexes. Instead of scanning the entire index first, ClickHouse now interleaves index checks with data reads. When the engine is about to read a granule, it first consults the corresponding index entry. If the index shows the granule can be skipped, it is never read. If not, the granule is processed while index evaluation continues for subsequent granules. For LIMIT queries, execution stops as soon as enough rows are found, and both index checks and data reads halt immediately.

This change removes startup delays and avoids unnecessary work. In testing on a 1 billion row table with a bloom filter index larger than 2 GiB, a simple LIMIT 1 query ran more than 4x faster with streaming indexes enabled, dropping from around 10 seconds to roughly 2.4 seconds.

This feature is controlled by the `use_skip_indexes_on_data_read` setting (defaults to 1 from 25.12) but enforced by ClickStack from 25.9.

Read the [full deep-dive on streaming support for skip indices](https://clickhouse.com/blog/clickhouse-release-25-09#streaming-for-secondary-indices).

### Using skip indices for disjunctions {#using-skip-indices-for-disjunctions}

Prior to 25.12, skip indexes were applied primarily to simple predicates or conjunctions such as AND clauses, allowing ClickHouse to prune granules and reduce unnecessary data reads. Disjunctions, such as OR conditions, did not benefit from index pruning. With newer releases, skip indexes can now also be applied to disjunctive queries, enabling pruning even when queries contain OR logic. 

This behavior is controlled by `use_skip_indexes_for_disjunctions`, which is enabled by default. As a result, ClickStack automatically benefits from improved pruning and reduced data scans for a wider range of real-world query patterns.

### Lazy materializations {#lazy-materializations}

ClickHouse has long relied on layered I/O optimizations such as columnar storage, primary and secondary indexes, projections, and PREWHERE to reduce the amount of data read from disk. Traditionally, once rows passed the WHERE clause, all referenced columns for those rows would be loaded before operations such as sorting, aggregation, or LIMIT were applied. In many analytical queries, especially Top-N patterns, this meant reading large columns that were ultimately unnecessary for producing the final result.

Lazy materialization, introduced in ClickHouse 25.4 and enabled by default, changes this behavior. Instead of eagerly loading all selected columns, ClickHouse defers reading columns until they are actually required by the execution plan. For example, when a query performs an `ORDER BY … LIMIT`, the engine can first determine the top rows using only the ordering column, and only then read the remaining columns for those final rows. This reduces I/O, memory usage, and latency, particularly for wide tables or queries returning a small number of rows from very large datasets. If you're curious as to the internals and looking for a deep dive, we recommend the excellent blog post [“ClickHouse gets lazier (and faster): Introducing lazy materialization”](https://clickhouse.com/blog/clickhouse-gets-lazier-and-faster-introducing-lazy-materialization#speed-without-filters-lazy-materialization-in-isolation).

Since this optimization was default since 25.4, users have been enjoying this for some time. However, this optimization is only applied if the limit is below a specified threshold [`query_plan_max_limit_for_lazy_materialization`](https://clickhouse.com/docs/operations/settings/settings#query_plan_max_limit_for_lazy_materialization). By default, this has a value of 10,000. 

In our own testing against typical ClickStack access patterns for log and trace search, we observed that result sets up to 100,000 rows still benefit significantly from lazy materialization - in large part to [recent changes which make further optimizations to this feature](https://clickhouse.com/blog/clickhouse-release-25-12#what-changed-in-2512). As a result, in the latest version of ClickStack, we increase this threshold to 100,000 to extend the performance gains to a broader range of real-world queries.

## Alerts on number charts {#alerts-on-number-charts}

We continue to expand alerting capabilities in ClickStack. Last year, we introduced [alerts on saved searches and charts](https://clickhouse.com/docs/use-cases/observability/clickstack/alerts). In the latest release, users can now create alerts directly on number charts as well.

This is ideal for simple, static threshold-based alerting. For example, if a number tile represents an error rate, request volume, latency, or any other key metric, you can now trigger an alert when it crosses a defined threshold. The workflow is consistent with existing alerting, making it straightforward to apply to existing dashboards.

metric_alerting.mp4

This is a small but practical addition, and part of a broader effort to make alerting more flexible and powerful. Expect more advanced alerting capabilities in upcoming releases.


Februarys' ClickStack update brings major improvements to both Cloud and open source, including new query workflows, enhanced metrics exploration, performance optimizations, and expanded alerting options.

large_clickstack_feb2026_image2.png

medium_clickstack_feb2026_image2.png

small_clickstack_feb2026_image2.png

thumbnail_clickstack_feb2026_image2.png

clickstack_feb2026_image2.png

What's new in ClickStack. February '26.

## TLDR; {#tldr}

With 26.2, we are introducing a new distribution method: ClickStack UI embedded in ClickHouse. The ClickStack UI is now distributed and embedded directly in the ClickHouse binary, making it easy to experiment with observability on your local instance, explore your own datasets, and even inspect ClickHouse itself.  Simply navigate to https://localhost:8123, select "ClickStack", and start exploring.

## Introduction {#introduction}

Historically, ClickStack has been available through Docker-based distributions. You can run the [full stack in a single container](https://clickhouse.com/docs/use-cases/observability/clickstack/deployment/all-in-one) for testing and experimentation, or deploy [each component independently](https://clickhouse.com/docs/use-cases/observability/clickstack/deployment/hyperdx-only) when moving to production - running the UI, collector, and ClickHouse separately using [tools such as Helm](https://clickhouse.com/docs/use-cases/observability/clickstack/deployment/helm).

More recently, [we introduced a managed ClickStack offering](https://clickhouse.com/blog/introducing-managed-clickstack-beta) in ClickHouse Cloud, where we host both the UI and ClickHouse. Users benefit from integrated authentication along with ClickHouse Cloud's separation of storage and compute - enabling both long-term data retention in object storage while allowing independent scaling of compute to minimize the cost per GB.

**From 26.2, we are adding a 3rd option.**

The ClickStack UI now comes embedded in the ClickHouse binary itself. At first glance, embedding a web application into a high-performance C++ database might sound like it would significantly increase the binary size. In practice, we have kept the additional footprint under 4.1 MB, ensuring installation remains lightweight and fast.

This means that installing ClickHouse now gives you ClickStack out of the box. Whether you use Docker, download the binary, or install via your favorite package manager, ClickStack is immediately available. Simply install ClickHouse, navigate to [http://localhost:8123](http://localhost:8123), and select ClickStack from the menu. Within seconds, you can begin exploring your logs, traces, and metrics.

<iframe width="768" height="432" src="https://www.youtube.com/embed/s1MGNcVNvNg?si=vO78XutzyvwGbHZM" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

## Built for Exploration and Local Development {#built-for-exploration-and-local-development}

The embedded version of the ClickStack UI  is designed for local exploration, learning, and exploring your own ClickHouse data with an observability UI. It is not intended for production deployments.

This distribution makes it easy to experiment with observability on your local ClickHouse instance, explore your own datasets, and even inspect ClickHouse itself. ClickHouse already exposes rich internal logs and metrics that are invaluable for diagnosing and optimizing performance. The ClickStack UI provides convenient ways to visualize this data and better understand how your instance behaves.

large_clickstack_mar2026_image4.png

medium_clickstack_mar2026_image4.png

small_clickstack_mar2026_image4.png

thumbnail_clickstack_mar2026_image4.png

clickstack_mar2026_image4.png

large_clickstack_mar2026_image7.png

medium_clickstack_mar2026_image7.png

small_clickstack_mar2026_image7.png

thumbnail_clickstack_mar2026_image7.png

clickstack_mar2026_image7.png

large_clickstack_mar2026_image1.png

medium_clickstack_mar2026_image1.png

small_clickstack_mar2026_image1.png

thumbnail_clickstack_mar2026_image1.png

clickstack_mar2026_image1.png

large_clickstack_mar2026_image9.png

medium_clickstack_mar2026_image9.png

small_clickstack_mar2026_image9.png

thumbnail_clickstack_mar2026_image9.png

clickstack_mar2026_image9.png

> The ClickHouse preset dashboard can be useful for diagnosing local issues and performance problems. Users can also search their local logs and build visualizations over system metric tables.

For larger or production deployments, we always recommend running ClickStack components separately.

The embedded version also intentionally omits certain capabilities to keep the distribution size small and the experience simple. There is no persistent state storage so alerting is disabled, as well as dashboard and querying persistence. [Event pattern](https://clickhouse.com/docs/use-cases/observability/clickstack/event_patterns) functionality is also not included to keep the size small as this requires [a WASM Python runtime](https://clickhouse.com/blog/event-patterns-clickstack#how-clickstack-implements-event-patterns).

Some of these limitations may be addressed in the future using approaches such as browser based storage, but for now the focus is simplicity and approachability.

If you plan to operate ClickStack at scale, or require alerting and persistence, the [open source docker versions](https://clickhouse.com/docs/use-cases/observability/clickstack/getting-started/oss) or [managed cloud](https://clickhouse.com/docs/use-cases/observability/clickstack/getting-started/managed) offering remain the recommended path.

## The technical challenges {#the-technical-challenges}

For the curious reader, embedding a full web application inside a C++ database binary involved some interesting engineering decisions.

### Assumptions {#assumptions}

Embedding ClickStack inside ClickHouse meant working within a strict set of conditions defined by the core team, reflecting the engineering standards expected of the ClickHouse binary:

1. Adding a [Node.js](http://node.js) dependency to ClickHouse is a non-starter
2. Files must be embedded in the binary, not lingering somewhere in the file system
3. ClickStack should not significantly inflate the binary size

### The Next.js parts {#the-nextjs-parts}

The UI that powers ClickStack, HyperDX, is a Next.js application. For those familiar, Next.js is a full-stack framework that renders pages on the server before serving, meaning that both the frontend and the backend are bundled into an application. It allows you to serve both static pages and dynamic HTML. However, serving dynamic pages without introducing a Node.js dependency would mean rewriting a lot of the Next.js internals. This meant serving dynamic pages was off the table. Luckily, ClickStack heavily uses static pages. There is still React running in the browser, but very little dynamic server-side rendering ever occurs.

ClickHouse has some existing HTML pages,  such as `play.html` for running queries in a WebUI, and `dashboards.html` for some extremely helpful dashboards to see the health of your ClickHouse instance. The `dashboards.html` page even loads some JavaScript!

However, both are a far cry from the complexity of serving a webpack output from a modern full-featured website like ClickStack. I'll get to that complexity in the [Bundling into ClickHouse](/blog/clickstack-embedded-clickhouse#bundling-into-clickhouse) section, but the existing web pages meant we could add an additional handler with just a little custom functionality.

### ClickStack existing variations and connecting to ClickHouse {#clickstack-existing-variations-and-connecting-to-clickhouse}

ClickStack already has a few  dependencies on which it relies for core functionality. The standard application includes Next.js, Express, and MongoDB. Express and MongoDB are primarily used for the CRUD persistence layer for saved searches, dashboards, and sources. The Express server also serves as a proxy for ClickHouse,  while also handling authentication to ensure DB credentials are not leaked to the frontend. It was safe to assume that the Express backend, MongoDB, and a proxy layer would not be available when embedding ClickStack in ClickHouse.

However, there already existed a [demo site](http://play-clickstack.clickhouse.com) with most capabilities we needed; connections stored in session storage, sources persisted in local storage, and ability to query ClickHouse directly without a proxy layer. The only modifications needed would be to adjust all links with the prefix "/clickstack". With this mechanism, we could attempt bundling into ClickHouse.

> We also decided to remove `pyodide`, a WASM Python runtime for the browser used for ClickStack's "Event Patterns" feature, purely because its size would inflate the ClickHouse binary size by more than we are comfortable with.

### Bundling into ClickHouse {#bundling-into-clickhouse}

ClickHouse uses many 3rd-party libraries and manages them via git submodules. This means that updating a version of a dependency is as simple as checking out a specific commit and rerunning the ClickHouse build. This provides us with the basic foundation to ensure that upgrading to a newer ClickStack version is potentially easy if we can provide it as a usable sub-module.

Building ClickHouse requires many dependent tools such as `cmake`, `ccache`, `ninja`, and many more. But NOT Node.js. For the purpose of reducing friction in local development as well as build times, this meant adding a new dependency with rather large implications like [node.js](http://node.js) was not an option. A good alternative is to generate a static bundle upon release and included directly in a git submodule. As we didn't want to clutter the ClickStack repo, this meant creating a new repo that can reproducibly check out a ClickStack version, build the static output, and update the bundle - ideally all automated upon the release of a new ClickStack version.

But we still have an issue - the files are now present in a ClickHouse build, but how can they be embedded?

C++ does have an #embed macro that allows embedding known files as raw bytes rather than as a file. Unfortunately, a feature of [Next.js](http://next.js) is that it outputs seemingly randomized file names, and lots of them. To handle this, we  generate a C++ file on the fly using some `cmake` magic. It does the following:

1. Creates a new file with some static definitions, specifically a struct definition that includes the file name, bytes, and MIME type
2. Find all files in contrib/clickstack/out
3. Sort by name
4. For each file
   1. Gzip the file (to reduce binary size + bytes shipped to browser)
   2. Generate an entry in an array

The generated file is then simply #included. Then, when a request is made to the `/clickstack` HTTP handler, there is a binary search for the file. If it is found, the file is returned with the appropriate MIME type. In the browser, the user must supply some username and password credentials to authenticate against ClickHouse - these are then used to directly query  ClickHouse over HTTP.

![](/uploads/clickstack_mar2026_image3_ab1eabc337.png)

The result is a very lean addition, around 4.2mb embedded directly into the actual binary itself.

## Getting Started {#getting-started}

To try ClickStack embedded in ClickHouse, install ClickHouse as you normally would. You can use the one-line installer:

<pre><code type='click-ui' language='bash'>
curl https://clickhouse.com/ | sh
</code></pre>

Or see the Open Source Quick Start [guide](https://clickhouse.com/docs/getting-started/quick-start/oss) for alternatives.

For this example, we will enable internal logs so you can explore your own ClickHouse instance, including executed queries and resource usage.

After downloading the binary, move to the directory where you want ClickHouse to store its data. Then create a configuration snippet that enables the query and metric logs:

<pre><code type='click-ui' language='bash'>
mkdir -p config.d && echo "&lt;clickhouse&gt;&lt;query_log&gt;&lt;database&gt;system&lt;/database&gt;&lt;table&gt;query_log&lt;/table&gt;&lt;/query_log&gt;&lt;query_thread_log&gt;&lt;database&gt;system&lt;/database&gt;&lt;table&gt;query_thread_log&lt;/table&gt;&lt;/query_thread_log&gt;&lt;query_views_log&gt;&lt;database&gt;system&lt;/database&gt;&lt;table&gt;query_views_log&lt;/table&gt;&lt;/query_views_log&gt;&lt;metric_log&gt;&lt;database&gt;system&lt;/database&gt;&lt;table&gt;metric_log&lt;/table&gt;&lt;/metric_log&gt;&lt;asynchronous_metric_log&gt;&lt;database&gt;system&lt;/database&gt;&lt;table&gt;asynchronous_metric_log&lt;/table&gt;&lt;/asynchronous_metric_log&gt;&lt;/clickhouse&gt;" | sudo tee ./config.d/query_logs.xml &gt; /dev/null
</code></pre>


This appends to the default configuration and enables system log tables.

Start the server and open your browser at [http://localhost:8123/clickstack](http://localhost:8123/clickstack)

<pre><code type='click-ui' language='bash'>
./clickhouse server
</code></pre>

A connection to the local instance is created automatically. If you already have OpenTelemetry data loaded, ClickStack will detect it and create sources automatically. On a fresh installation, you will be prompted to create a source. For this example, create a new **Log Source** that points to `system.query_log`.

![](/uploads/clickstack_mar2026_image8_3e2b3fa28f.png)

> Config: `Name: Query Logs`
> 
> `Database: system`
> 
> `Table: query_log`
> 
> `Timestamp Column: event_time`
> 
> `Default Select: event_time, query_kind, query, databases, tables, initial_user, projections, memory_usage, written_rows, read_rows, query_duration_ms`.*

Save the source. You will be redirected to the search view, where query logs should immediately begin appearing.

At this point, you are observing your own ClickHouse instance.

![](/uploads/clickstack_mar2026_image5_4ac157885b.png)

Feel free to open the play UI at [http://localhost:8213/play](http://localhost:8213/play), run a few queries and watch them appear in ClickStack. With the default selection you can view the execution time, the memory usage and other useful metadata such as the projections used.

We also include a built-in ClickHouse preset dashboard, available from the left navigation menu. It provides insights into query latency and slow queries, highlights the most time consuming query patterns, shows query counts per table, and surfaces key system metrics such as CPU usage, memory consumption, S3 requests, and insert activity. Together, these views give you immediate observability into your ClickHouse instance, powered entirely by the embedded ClickStack UI.

![](/uploads/clickstack_mar2026_image2_42373b1362.png)

To continue exploring ClickStack and learning its features, we recommend trying it with one of our [sample datasets](https://clickhouse.com/docs/use-cases/observability/clickstack/sample-datasets). These include sample [observability data](https://clickhouse.com/docs/use-cases/observability/clickstack/getting-started/sample-data) from the [OpenTelemetry demo](https://github.com/ClickHouse/opentelemetry-demo), along with examples for [exploring session replay functionality](https://clickhouse.com/docs/use-cases/observability/clickstack/example-datasets/session-replay-demo) and monitoring your [local infrastructure and ClickHouse instance](https://clickhouse.com/docs/use-cases/observability/clickstack/getting-started/local-data).

## Conclusion {#conclusion}

With ClickStack now embedded directly in ClickHouse, getting started with observability is as simple as installing the database itself. There is no additional setup, no separate services to run, and no external UI to deploy. Within seconds, you can begin exploring logs, traces, metrics, and even ClickHouse's own internal behavior.

Our hope is that this distribution lowers the barrier to entry and makes it easier to discover the value of ClickStack using your own local datasets. It provides a practical environment for learning the product, running demos, training teams, experimenting with queries, and understanding how ClickHouse behaves during development.

We look forward to seeing how the community uses it, and contributes to its evolution.


With ClickHouse 26.2, the ClickStack observability UI is embedded directly in the binary. Install ClickHouse, open localhost:8123, and start exploring your logs, traces, and metrics - no extra setup required.

The ClickStack Team

Blog posts by The ClickStack Team

What's new in ClickStack - April 2026

otel.fyi - OTel Collector docs made simple

What's new in ClickStack - March 2026

We taught ClickStack to read your logs like a detective novel

What's new in ClickStack. February '26.

Introducing ClickStack embedded in ClickHouse