chmonitorQueries
Monitor live, historical, failed, slow, and expensive queries with thread-level breakdown and per-user resource analysis.
The Queries feature covers the full lifecycle of query observability — live execution, historical logs, failures, resource cost, thread-level breakdown, and per-user process summaries.
| Routes | /running-queries, /history-queries, /failed-queries, /expensive-queries, /slow-queries, /explain, /query-views-log, /queries/thread-analysis, /user-processes, /query-metric-log |
| Feature id | queries |
| Default access | public |
| Requires auth | No (set CHM_FEATURE_QUERIES_ACCESS=authenticated to gate) |
| System tables | system.processes, system.query_log, system.query_views_log, system.query_thread_log, system.user_processes, system.query_metric_log, system.errors |
| ClickHouse grants | SELECT on the system tables above; KILL QUERY for the kill-query action |
What it does
The Queries feature answers the full lifecycle of query observability:
- Live — what is running right now, elapsed time, memory, thread count.
- History — finished queries with full metrics (CPU, memory, read/write rows and bytes, duration).
- Failures — queries that errored, with error codes and messages.
- Cost — top queries by CPU, duration, or memory over a selected time window.
- Thread & parallelization — per-thread breakdown of a single query execution.
- Materialized view log — how each materialized view was triggered and how long it took.
- User processes — aggregated per-user resource usage from live processes.
- Query metric log — per-query resource samples taken throughout a query's lifetime.
The Explain page does not query a log table; it runs EXPLAIN statements against the connected host interactively.
Using it
Each question maps to a dedicated page.
| Page | Route | What it shows | System tables |
|---|---|---|---|
| Running Queries | /running-queries | Live query list: elapsed, memory, read rows, thread count; kill action | system.processes |
| History Queries | /history-queries | Finished queries with full metrics; filter by user, query type, time range | system.query_log |
| Failed Queries | /failed-queries | Queries that ended with an exception; error code and message | system.query_log |
| Most Expensive Queries | /expensive-queries | Top queries by CPU time, duration, or memory | system.query_log |
| Slow Queries | /slow-queries | Top 10 slowest finished queries by duration | system.query_log |
| Explain | /explain | Interactive EXPLAIN for any SQL; no log table queried | — |
| Query Views Log | /query-views-log | Materialized view execution history: status, duration, row throughput | system.query_views_log |
| Thread & Parallelization | /queries/thread-analysis | Thread-level performance breakdown for individual query executions | system.query_thread_log |
| User Processes | /user-processes | Per-user memory and resource summary from live processes | system.user_processes |
| Query Metric Log | /query-metric-log | Per-query resource timeline sampled over each query's lifetime | system.query_metric_log |
KILL QUERY privilege required
The kill-query button on /running-queries issues KILL QUERY. The ClickHouse user configured via CLICKHOUSE_USER must have the KILL QUERY privilege. Without it, the button returns an error.
Optional system tables
Several pages depend on tables that must be explicitly enabled in the ClickHouse server config. Pages backed by a missing table show an empty state rather than an error.
| Table | Config key | Default |
|---|---|---|
system.query_views_log | <query_views_log> | disabled on many installs |
system.query_thread_log | <query_thread_log> | disabled on many installs |
system.query_metric_log | <query_metric_log> | disabled; high-cardinality on busy clusters |
Additional behavior to keep in mind:
system.query_log— ClickHouse writes asynchronously. Very recent queries (< a few seconds old) may not appear in history pages yet. Retention and flush intervals are set viaquery_log.flush_interval_millisecondsandquery_log.ttlin the ClickHouse server config, not by chmonitor.system.user_processes— available since ClickHouse 22.6. Earlier versions show a table-not-found notice.system.errors— the Common Errors view readssystem.errors, which is always present and contains aggregated error-code counts (not per-query).
Permissions & access
All query pages fall under the queries feature id:
CHM_FEATURE_QUERIES_ACCESS=authenticated
# Disable the whole feature
CHM_FEATURE_QUERIES_ENABLED=false
# or
CHM_DISABLED_FEATURES=queries# CHM_CONFIG_FILE (TOML)
[features.queries]
access = "authenticated"When disabled, all sub-routes are removed from the nav and return a disabled screen on direct visit.
There is no feature-specific configuration beyond the global query settings:
CLICKHOUSE_MAX_EXECUTION_TIME=60 # per-query timeout in seconds