ClickHouse built-in dashboard setup

What the ClickHouse built-in observability dashboard is for

The /dashboard page is a web interface served by the ClickHouse server itself that shows live health charts for one node, such as query activity, memory use and merges. For a team running self-managed ClickHouse that needs a quick look at whether the server is healthy before a full monitoring stack exists, it is often enough for a first check, a small test cluster or an incident walk-through. It is not a substitute for historical alerting, cross-node views or long retention. According to the ClickHouse documentation, the dashboard is intended as a lightweight diagnostic view, so confirm the exact charts, the URL path, the port and the access behavior against the documentation for the version you run, because these details change between releases.

Before you rely on the page, decide who can reach it. The dashboard exposes operational detail about queries and resources, so treat it as an internal administrative endpoint. Check which release lines are currently supported in the ClickHouse security policy, because a server on an unsupported version should not be exposed to anyone, and confirm which authentication path protects the page in your build. Plan network restrictions and user access for it the same way you would for the HTTP interface, and record the decision in your runbook so that the next operator does not assume the page is public or private by default.

Plan for the dashboard to be a starting point, not your alerting system. Use it to confirm that a node is up, that merges and memory look normal during a load test, and that parts are not piling up during ingestion. Move to a Prometheus scrape and alert rules when you need trends across replicas, alert routing, or retention beyond the session. A ClickStack setup suits teams that want to explore ClickHouse's own system tables in depth. Note which of these tools your team will own before go-live, because the dashboard alone does not cover shard-level or Keeper-level questions.

Built-in dashboard, Prometheus and Grafana, or ClickStack: which fits

This table compares the built-in /dashboard page, Prometheus scraping with Grafana, and ClickStack with HyperDX for watching a self-managed ClickHouse cluster. Read each row against your on-call model, your retention requirements and your access rules. The main takeaway: the built-in page suits quick live checks, Prometheus suits alerting and longer history, and ClickStack suits deep investigation of telemetry stored in ClickHouse.

Consideration	Built-in /dashboard	Prometheus with Grafana	ClickStack with HyperDX
Main purpose	Live charts of server activity, queries, merges and resource use	Scraping numeric metrics over time, alerting and dashboards	Searching and correlating logs, traces and system tables
Who uses it	Operators checking a node during an incident	Platform and SRE teams running on-call and capacity reviews	Engineers debugging slow queries, inserts and infrastructure
Retention and history	Short, live view; confirm what history, if any, your version keeps	Set by Prometheus storage retention; confirm your configured period	Set by the telemetry tables and TTL you define; confirm defaults
Alerting	Visual flags only; confirm whether your version offers alerts	Alert rules evaluated against scraped metrics	Kept separate from alerting; confirm current alerting features
Extra components to run	None beyond the ClickHouse server	Prometheus server, Grafana and scrape configuration	HyperDX UI and a ClickHouse cluster for telemetry storage
Access control needs	A ClickHouse user with permission to open the page; restrict it	Scrape endpoint reachable only from Prometheus; restrict Grafana users	HyperDX accounts mapped to ClickHouse users with read-only roles
Typical trigger for choosing it	A small team that needs a quick health view on one cluster	Alerts on parts, memory, replication lag or merges across clusters	Repeated slow-query or insert investigations needing system table detail

Which dashboard charts flag merge, memory and parts problems early

ClickHouse MergeTree tables write small parts on every insert and combine them in the background. When merges fall behind ingest, reads slow down and part counts climb. Start with the merge-related charts on the dashboard and compare merge activity with ingest volume over the same window.

Active merge count: A count that rises and stays high during ingest suggests merge demand is exceeding background capacity.
Merge pool saturation: If background pool tasks sit at their configured limit, review the pool size settings for your version before changing anything.
Long-running merges: Very large parts can keep merges active for a long time. Check system.merges for elapsed time and progress.
Flat activity during heavy ingest: A flat line near zero while parts accumulate can mean merges are blocked. Check system.replication_queue on replicated tables and free disk space, since merges need room to write new parts.

Confirm chart names and any alert thresholds against your running version, and check whether merge activity recovers once ingest pauses.

Memory charts show server resident memory, query memory and cache usage. Memory that rises with query load and falls afterward is normal behavior. Memory that stays high after load drops, or that climbs steadily through merge and insert peaks, needs investigation before limits are raised.

Resident memory after load: Check whether memory returns to a lower level once queries finish. A steady climb across idle periods suggests retained allocations or growing caches.
Peak query memory: Compare peaks with the memory limits in your settings profiles. Repeated peaks near the limit usually point to heavy joins, large aggregations or wide result sets.
Cache sizes: Cache metrics should stay within configured bounds. Growth beyond what the configuration allows is a reason to review cache settings.
Concurrency spikes: Spikes that line up with more running queries in system.processes point to too many concurrent heavy queries, so check query concurrency and quotas.
Merge and insert memory: Peaks that coincide with large merges or big inserts should be checked against system.merges and the insert pattern.

Confirm metric names in your version, then reproduce the spike while watching system.processes and system.asynchronous_metrics to see which workload drives it.

Parts are the on-disk units of MergeTree tables. Each insert creates at least one part, so a steadily rising part count per table or partition is the earliest warning before ClickHouse starts rejecting inserts. Read the parts charts together with merge activity, because the two signals usually move together.

Parts per partition: Steady growth during ingest with no matching decline means merges or insert batching need attention. Check system.parts for the partitions that are growing.
Insert batch size: Many small inserts create many small parts. Review insert frequency and row counts per insert in system.query_log.
Replication backlog: On replicated tables, a growing queue can mean parts are waiting to be fetched or merged on a replica. Check system.replication_queue.
Partition design: A large number of partitions multiplies the number of parts a table holds. Review the partition key against your retention and query patterns.
Error messages: When the limit is reached, inserts fail with a too many parts error. Treat the early climb on the chart as the signal to act, not the error itself.

Confirm the thresholds that apply to your version and cross-check the part counts with system.parts before changing batching, partitioning or merge settings.

How to enable and reach the ClickHouse built-in dashboard

This sequence turns the built-in /dashboard page on for one server, limits who can reach it, and proves with recorded tests that allowed networks get in and denied networks do not. The output is a short access record your team can repeat after every upgrade.

Confirm the server version and HTTP interface
The platform engineer running the cluster records the exact server version with clickhouse-server --version or by querying SELECT version(), then checks the HTTP interface settings in the configuration reference for that version. Confirm the HTTP port, whether the HTTP interface is enabled, and how it is bound to network addresses. Do not rely on remembered defaults. Done means you have a written note of the version and the HTTP settings that apply to it.
Confirm the dashboard is served from the HTTP interface
Before changing anything, the engineer checks that the server answers HTTP requests on the port recorded in the previous step, for example with a plain health request from a host inside the management network. Confirm in the configuration reference for your version whether the dashboard is available under the HTTP interface and which settings control it. Done means the HTTP interface responds and you know which setting governs the dashboard on this version.
Enable the dashboard in server configuration
The engineer makes the change in a server configuration file under version control, using the setting name confirmed in the configuration reference, and rolls it out to one node first. Keep the change narrow so that no other HTTP behavior is altered in the same edit. Restart or reload according to the procedure for your deployment. Done means the change is committed, applied to the test node, and the server starts without configuration errors in its logs.
Restrict access to the dashboard
The security or platform engineer limits the dashboard to a named set of management hosts or subnets, using the network controls your version supports, such as listen addresses, firewall rules or a reverse proxy in front of the server. Check the access control documentation so that the dashboard's user account is not the unrestricted default user, and that the account used for viewing has only the rights it needs. Done means the allowed source ranges and the user for dashboard access are written down and approved by the owner of the cluster.
Test access from an allowed network
From a host inside the approved management range, the engineer opens the dashboard in a browser and attempts a login with the intended account. Record the URL used, the account, the time, and whether the page loads and shows live server data. If authentication is required, confirm that the login succeeds and that the page refreshes its charts. Done means a dated entry in the access record shows success from an allowed source.
Test denial from a network outside the allowed range
From a host outside the approved ranges, such as a general office or public network segment, the engineer repeats the same request. The connection should be refused, time out, or be blocked by the reverse proxy, and the dashboard must not load. Also try the request without credentials from an allowed host to confirm that authentication is enforced. Record the result, the source host, and the response code or error. Done means denial is shown for both the unlisted network and the missing credentials.
Record the check results and repeat after changes
The engineer saves the server version, configuration commit, allowed and denied test results, and the account used into the operations runbook, and assigns a reviewer. Repeat the allowed and denied tests after each version upgrade, configuration change, or firewall update, because release notes can change settings. Done means the access record is filed and the next review date is set by the cluster owner.

How to protect the ClickHouse built-in dashboard endpoint

The /dashboard page is served by the same HTTP interface that clients use, so it inherits that interface's exposure. The controls below limit who can reach it, who can sign in, and how sign-ins are recorded. Confirm how the dashboard authenticates in the exact version you run before you rely on any of them.

Restrict network exposure

Bind the HTTP interface only where operators need it, and allow access to port 8123 from operator networks or a reverse proxy rather than from general user networks. Put the dashboard behind a jump host or VPN if your operators work remotely. Check the listening address and firewall rules from outside the cluster, not only from the server itself.

Require authenticated access

Treat the dashboard as an administrative surface and confirm that every request to it requires a valid ClickHouse login in your version. Test this with an unauthenticated request from an allowed network. If the page loads without credentials, fix the authentication configuration before you expose it to anyone else.

Use a least-privilege operator account

Create a dedicated user for dashboard access and grant it only the privileges needed to read the system tables the charts query. The access control documentation describes users, roles and settings profiles for this. Avoid granting broad administrative rights, because anyone with the login can read query text and cluster metadata.

Retire the default user

The default user starts with all permissions. Do not use it for dashboard access, and restrict or disable it once named accounts exist. The access control documentation recommends this, and it removes a well-known username from the attack surface that scanners try first.

Enable TLS on the HTTP interface

Serve the dashboard over HTTPS so credentials and query data are not sent in clear text across the network. Use certificates issued by your internal CA and confirm that clients and proxies validate them. Check the TLS configuration in the server settings for your release, because the setup differs between installation methods.

Log and review access

Record who opens the dashboard and when, using the server query logs and your reverse proxy or load balancer logs. Review failed logins and unusual source addresses on a set schedule. Keep these logs outside the ClickHouse data path so a failure there does not erase the evidence.

Why the built-in dashboard does not replace alerting

The built-in dashboard at /dashboard is a page that a person has to open and read. It shows the server's current state and recent history, which makes it useful once someone is already investigating, but it cannot notify anyone when a problem starts while nobody is looking. Alert rules work differently. A metrics pipeline evaluates thresholds on a schedule and sends notifications to on-call staff through a route they actually monitor. Treat the dashboard as the place to investigate after an alert fires, and treat alert rules as the mechanism that brings someone there. Confirm which team owns alert routing and test that a notification reaches a person outside working hours.

Operators should use both, with clear roles for each. During an incident, open /dashboard next to the metrics named in the alert, and note what the merge, memory and parts charts show so the timeline is accurate. Between incidents, do not depend on someone happening to open the page. Send the same signals to a metrics system such as Prometheus, then set alert rules on merge backlog, memory pressure and part counts, using thresholds your team has agreed on for your workload. After any cluster change, such as a version upgrade or a new node, send a test alert and confirm that it reaches the on-call channel. A rule that has never fired in a test is unproven.

The dashboard also says nothing about replication or backups, so both need their own verification. Replicated tables depend on ClickHouse Keeper, and the replication documentation states that a recovered replica automatically syncs missing data from a healthy replica. That behavior is a reason to confirm that replicas are catching up after an outage, not a reason to assume it. Replication also does not protect against human error or corruption, which is why the *Backup and restore* documentation recommends regular restore tests on a spare cluster. Ask your team to schedule those tests, record their results, and alert on failed or overdue runs.

Limits to confirm before relying on the built-in dashboard

The built-in dashboard is useful for a quick look at a single ClickHouse server, but it has boundaries that matter once it is part of how your team watches production. The cards below list what to confirm with the vendor documentation and in a pre-production environment before you depend on it for alerts, capacity decisions or incident evidence.

History depth and retention

Find out whether the dashboard keeps any history after you close the page, and for how long. A chart that only shows the last few minutes cannot show whether merges or memory grew gradually over days. Load a known workload in pre-production, leave it running, and confirm which time windows are still visible the next day. Record what you can see directly in the product so you know what to export or store elsewhere.

Cluster-wide views

Confirm whether the page shows one node or aggregates across replicas and shards. A replicated cluster can look healthy on the node you happen to open while another replica falls behind on merges or fetches. Open the page on each node in a test cluster with an induced lag and check whether any view points you to the other nodes. If it only covers one server, plan cross-node comparison in Prometheus or a log query.

Export and alerting options

Ask whether charts or raw values can be exported as files, pulled through an API, or used to trigger notifications. Without an export path, the dashboard cannot feed a ticket, an alert rule or a post-incident review. Test the export path in pre-production, including whether the output is machine-readable and whether it reflects the same time window you see on screen.

Chart customization

Confirm which charts you can add, remove, rename or set thresholds on. Teams often need a chart for a specific table, a merge backlog threshold or a memory ceiling tied to their hardware. Check in a test instance whether a custom query or metric can be placed on the page, and whether the layout survives an upgrade. If the answer is no, record which signals must come from Prometheus or system tables instead.

Behavior under heavy load

The dashboard runs on the server it observes, so it competes for the same CPU and memory during an incident. Ask the vendor how the page behaves when the node is saturated, and test it by running a heavy merge or large query in pre-production while the page is open. Measure whether the page slows, times out or adds load. Plan an independent scrape path for the moments you most need visibility.

Versions and release lines

Confirm which ClickHouse versions include the page and whether its charts change between stable and LTS lines. The security policy lists versions 26.9, 26.8, 26.7 and 26.3 as supported with security updates, and only those lines should be in production. Check the changelog for your exact version before upgrading, because a page that exists in one release may be absent or changed in another.

Questions teams ask before they set up the ClickHouse dashboard

Is the built-in ClickHouse dashboard enough for production monitoring?

It is useful for live inspection, but most production teams also need history, alert routing and dashboards that outlive a single server. The built-in /dashboard page shows current activity and charts for the node you open it on, so it answers questions like whether merges are backing up or memory is climbing right now. It does not replace alerting with notification routing, long retention or cross-cluster views. Decide early which of those you require. If you need them, plan for Prometheus and Grafana or ClickStack alongside the dashboard rather than instead of it. Confirm the exact chart set against the version you run, because the dashboard changes between releases.

How long does setting up the dashboard take, and what drives that time?

The dashboard itself is enabled through the HTTP interface, so the direct setup work is small. The effort that varies comes from the decisions around it: how many clusters and nodes you run, whether the page must sit behind your identity provider, how the network path is designed, and what alerting you need. Each cluster adds access, certificate and firewall work. Ask any partner for a written scope that lists the clusters in scope, the access model, the network zones involved and the alert rules to be delivered, along with the acceptance tests. Timelines should follow from that list, not from a generic estimate.

What does the internal team need to provide for this work?

Your team needs someone who can explain the network zones, the identity provider and the on-call process, plus access to the ClickHouse servers and their configuration. Engineers who will read the charts need a working knowledge of parts, merges and memory in ClickHouse, or time to learn it. Security must approve where the dashboard can be reached from. Name these owners before work starts. A written scope should state which of these inputs the client supplies, which dates depend on them, and who signs off on each acceptance test.

Can our own engineers set up and protect the dashboard without outside help?

Yes, a team with ClickHouse operations experience can enable the page, restrict it and build the first alerts in-house. The work is manageable for one cluster. It gets harder when several clusters share an access model, when the page must use SSO, or when you need alerts that match your on-call rules. Check whether your engineers already maintain the server configuration, the reverse proxy and the identity integration. If those are owned by different teams, the coordination cost is often the larger part of the effort.

What does adding Prometheus or ClickStack cost, and why?

Costs come from the components you add, the people who build them and the infrastructure that runs them. Prometheus adds a scrape target, storage for time series, alert rules and usually Grafana dashboards. ClickStack adds a UI and its own storage and ingestion path for telemetry. Both recur as hardware, storage and maintenance. Ask any quote to separate one-time items such as design and build from recurring items such as retention storage, upgrades and on-call. Also ask which retention period the figures assume, because storage grows with it.

How should we secure access to the built-in dashboard?

Treat the dashboard as an administrative surface, because it exposes operational detail about your cluster. Do not leave it open to the network. Restrict who can reach the HTTP port, place the page behind an authenticating proxy or identity integration, and avoid sharing the default user. Use dedicated ClickHouse users with the smallest set of permissions, and review them with the access control documentation. Ask for a written list of who can reach the page, how access is logged and how credentials are rotated.

When should we bring in an outside partner for dashboard and monitoring work?

Bring in a partner when the monitoring scope spans several clusters, needs SSO and network design, or must meet a documented audit requirement for access and alerting. Also consider help when an alert is firing and the team cannot tell whether it is a parts, memory or replication problem. A partner should work from a written scope that names deliverables, owners, acceptance tests and the systems in scope. Ask for that scope in writing before work starts, and confirm how ongoing support is handled after handover.

How DeployOpen scopes and supports ClickHouse monitoring

DeployOpen treats the built-in dashboard as one part of a monitoring plan for self-managed ClickHouse, not a complete one. We agree the scope in writing, configure access and the charts your operators need inside your own infrastructure, then document and hand over the result so your team can run it.

How we scope

Inventory the ClickHouse versions, nodes, Keeper ensemble and networks the dashboard must reach before any change is made.
Agree in writing which dashboard charts, thresholds and escalation paths are in scope for your operators and on-call staff.
Confirm who may view the dashboard, which network paths expose it, and which monitoring tools stay outside this engagement.

How we build

Restrict the dashboard endpoint to approved networks and users, using the access controls your ClickHouse users and roles already define.
Test each flagged chart against a pre-production cluster with representative data so merge, memory and parts thresholds reflect your workload.
Record configuration, access rules and chart interpretation notes so the setup can be reviewed and repeated in other environments.

How we hand over

Deliver a written runbook explaining what each dashboard panel shows, what a warning means and the first checks operators should run.
Walk your operations team through the dashboard during a handover session, covering the criteria for moving to Prometheus or ClickStack.
Document the open items, such as alerting gaps or retention limits, that your team must confirm or own after the engagement ends.

How we support

Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts, and a quote follows from that scope.
Ongoing support, upgrades and continuous testing are available as a retainer if your team wants DeployOpen to keep the monitoring setup current.
Review the dashboard setup again after ClickHouse upgrades, since release changes can affect the metrics and panels your operators rely on.

Using the ClickHouse built-in observability dashboard