chmonitorchmonitor
Getting Started

ClickHouse user & grants

Create a minimal read-only ClickHouse user for chmonitor, with optional action grants and a recommended monitoring profile.

chmonitor needs a ClickHouse user with at minimum SELECT on system.*. Do not use an admin account for a shared dashboard. For GRANT CREATE ON my_db.* vs GRANT CREATE TABLE, ON CLUSTER, and SHOW GRANTS, see ClickHouse GRANT syntax.

Connecting a firewalled ClickHouse to Cloud?

If your ClickHouse is behind a firewall and you use the hosted Cloud, see Connect a firewalled ClickHouse (Cloudflare Tunnel, dedicated egress IPs, or a jump host).

Loading diagram…

Copy & paste: pick a permission level

Toggle the features you need — the SQL and XML output updates automatically. Replace your-password before running. The monitoring_profile body is in the recommended profile section below.

Select features

CREATE USER monitoring
  IDENTIFIED WITH sha256_password BY 'your-password'
  HOST ANY;

-- System tables (metrics, queries, merges, replicas, …)
GRANT SELECT ON system.* TO monitoring;
-- Required for some merge-aware queries
GRANT CREATE TEMPORARY TABLE ON *.* TO monitoring;

The static reference tabs below show every combination individually if you prefer to copy from them directly.

-- Monitoring dashboards only. Cannot kill queries, optimize, or mutate data.
CREATE USER monitoring
  IDENTIFIED WITH sha256_password BY 'your-password'
  HOST ANY;

-- All system tables (metrics, queries, merges, replicas, …)
GRANT SELECT ON system.* TO monitoring;

-- Required for some merge-aware queries
GRANT CREATE TEMPORARY TABLE ON *.* TO monitoring;
-- Monitoring dashboards + Data Explorer (query any table in any database).
-- SELECT ON *.* covers system.* as well — use only if you trust this account
-- to read all your databases.
CREATE USER monitoring
  IDENTIFIED WITH sha256_password BY 'your-password'
  HOST ANY;

GRANT SELECT ON *.* TO monitoring;
GRANT CREATE TEMPORARY TABLE ON *.* TO monitoring;
-- Read-only monitoring, plus Kill Query and Optimize Table actions.
-- AGENT_ENABLE_CONTROL_TOOLS=true is also required for the AI agent to use these.
CREATE USER monitoring
  IDENTIFIED WITH sha256_password BY 'your-password'
  HOST ANY;

GRANT SELECT ON system.* TO monitoring;
GRANT CREATE TEMPORARY TABLE ON *.* TO monitoring;
GRANT KILL QUERY ON *.* TO monitoring;
GRANT OPTIMIZE ON *.* TO monitoring;
<!-- /etc/clickhouse-server/users.d/monitoring.xml -->
<clickhouse>
  <users>
    <monitoring>
      <password_sha256_hex>REPLACE_WITH_SHA256_OF_YOUR_PASSWORD</password_sha256_hex>
      <networks><ip>::/0</ip></networks>
      <profile>monitoring_profile</profile>
      <grants>
        <query>GRANT SELECT ON system.*</query>
        <query>GRANT CREATE TEMPORARY TABLE ON *.*</query>
      </grants>
    </monitoring>
  </users>
</clickhouse>

Generate the hash: echo -n 'your-password' | sha256sum. See the recommended profile for the monitoring_profile body.

<!-- /etc/clickhouse-server/users.d/monitoring.xml -->
<!-- SELECT ON *.* covers system.* and every user database. -->
<clickhouse>
  <users>
    <monitoring>
      <password_sha256_hex>REPLACE_WITH_SHA256_OF_YOUR_PASSWORD</password_sha256_hex>
      <networks><ip>::/0</ip></networks>
      <profile>monitoring_profile</profile>
      <grants>
        <query>GRANT SELECT ON *.*</query>
        <query>GRANT CREATE TEMPORARY TABLE ON *.*</query>
      </grants>
    </monitoring>
  </users>
</clickhouse>

Generate the hash: echo -n 'your-password' | sha256sum. Run SYSTEM RELOAD CONFIG or restart ClickHouse after editing.

<!-- /etc/clickhouse-server/users.d/monitoring.xml -->
<!-- Read-only monitoring, plus Kill Query and Optimize Table. -->
<clickhouse>
  <users>
    <monitoring>
      <password_sha256_hex>REPLACE_WITH_SHA256_OF_YOUR_PASSWORD</password_sha256_hex>
      <networks><ip>::/0</ip></networks>
      <profile>monitoring_profile</profile>
      <grants>
        <query>GRANT SELECT ON system.*</query>
        <query>GRANT CREATE TEMPORARY TABLE ON *.*</query>
        <query>GRANT KILL QUERY ON *.*</query>
        <query>GRANT OPTIMIZE ON *.*</query>
      </grants>
    </monitoring>
  </users>
</clickhouse>

Generate the hash: echo -n 'your-password' | sha256sum. AGENT_ENABLE_CONTROL_TOOLS=true is also required for the AI agent to use Kill Query / Optimize.

Roles let you manage grants centrally and assign them to multiple users. Create the role via SQL first, then reference it from the user XML.

Step 1 — create the role (run once in a ClickHouse client):

CREATE ROLE IF NOT EXISTS monitoring_role;
GRANT SELECT ON system.* TO monitoring_role;
GRANT CREATE TEMPORARY TABLE ON *.* TO monitoring_role;

-- Optional: expand to Explorer or action support
-- GRANT SELECT ON *.* TO monitoring_role;
-- GRANT KILL QUERY ON *.* TO monitoring_role;
-- GRANT OPTIMIZE ON *.* TO monitoring_role;

Step 2 — user config (/etc/clickhouse-server/users.d/monitoring.xml):

<clickhouse>
  <users>
    <monitoring>
      <password_sha256_hex>REPLACE_WITH_SHA256_OF_YOUR_PASSWORD</password_sha256_hex>
      <networks><ip>::/0</ip></networks>
      <profile>monitoring_profile</profile>
      <grants>
        <query>GRANT monitoring_role TO monitoring</query>
      </grants>
    </monitoring>
  </users>
</clickhouse>

Generate the hash: echo -n 'your-password' | sha256sum. Run SYSTEM RELOAD CONFIG after editing the XML. Update grants on the role and they apply to all users holding it.

Optional extras

The tabs above already cover the three permission levels. Use these only if you need write-side extras.

Per-feature grants checklist

GRANT SELECT ON system.* covers most of the dashboard. Missing optional tables show a notice, not an error.

Multi-host setup

Each host can have its own user and password. Comma-separated values share positions:

CLICKHOUSE_HOST=https://prod-a:8443,https://prod-b:8443
CLICKHOUSE_USER=monitoring,monitoring
CLICKHOUSE_PASSWORD=secret-a,secret-b
CLICKHOUSE_NAME=prod-a,prod-b

CLICKHOUSE_HOST defines the host count. CLICKHOUSE_USER and CLICKHOUSE_PASSWORD may be a single shared value or one value per host. CLICKHOUSE_NAME is optional.

monitoring.xml
monitoring_profile.xml
<!-- /etc/clickhouse-server/users.d/monitoring_profile.xml -->
<clickhouse>
  <profiles>
    <monitoring_profile>
      <allow_experimental_analyzer>1</allow_experimental_analyzer>

      <!-- Optional: reduce repeated load from dashboard queries -->
      <use_query_cache>1</use_query_cache>
      <query_cache_ttl>50</query_cache_ttl>
      <query_cache_max_entries>0</query_cache_max_entries>
      <query_cache_system_table_handling>save</query_cache_system_table_handling>
      <query_cache_nondeterministic_function_handling>save</query_cache_nondeterministic_function_handling>
    </monitoring_profile>
  </profiles>

  <users>
    <monitoring>
      <profile>monitoring_profile</profile>
    </monitoring>
  </users>
</clickhouse>

Enable system tables

Enable system log tables so every dashboard feature has data to read.

Getting started

Run chmonitor against your ClickHouse instance in minutes.

Connect a firewalled ClickHouse

Reach a firewalled ClickHouse from the hosted Cloud without a brittle IP allowlist.

Environment variables

Every environment variable, grouped by category.

Getting started

Run chmonitor against your ClickHouse instance in minutes — three environment variables and one command, via Docker or from source.

Enable system tables

Enable and configure ClickHouse system log tables for full chmonitor feature coverage, including query_log, metric_log, and optional thread logs.

On this page

Copy & paste: pick a permission levelOptional extrasPer-feature grants checklistMulti-host setupRecommended ClickHouse profileRelated