chmonitor

Track active merges, historical merge performance, mutations, part moves, and the part-event timeline for all MergeTree tables.

Routes/merges, /merge-performance, /mutations, /moves, /part-log
Feature idoperations
Default accesspublic
Requires authNo (set CHM_FEATURE_OPERATIONS_ACCESS=authenticated to gate)
System tablessystem.merges, system.mutations, system.moves, system.part_log
ClickHouse grantsSELECT on the system tables above; KILL MUTATION for the kill-mutation action

What it does

Operations covers the background work MergeTree engines do continuously:

  • Merges — which parts are being merged right now, progress percentage, estimated completion, rows and bytes processed.
  • Merge performance — historical trends from the part log: merge size, duration, and throughput over time.
  • Mutations — ALTER TABLE ... UPDATE/DELETE operations: how many parts remain, any failures.
  • Moves — parts currently being moved between disks or volumes due to TTL or storage policy rules.
  • Part log — the full part-event history: part creation, merges, mutations, downloads from replicas, and removals.

All pages are read-only except the kill-mutation action on /mutations.

Pages

PageRouteWhat it showsSystem tables
Merges/mergesActive merge list: table, progress %, elapsed, rows/bytes merged, estimated finishsystem.merges
Merge Performance/merge-performanceHistorical merge stats from the part log: size buckets, duration trendssystem.part_log
Mutations/mutationsPending and completed mutations: parts_to_do, is_done, failure reason; kill actionsystem.mutations
Moves/movesIn-progress part moves: source/target disk, part name, size, elapsedsystem.moves
Part Log/part-logPart lifecycle events: NewPart, MergedPart, MutatedPart, DownloadedPart, RemovedPartsystem.part_log

Permissions & access

All sub-routes share the operations feature id:

## Gate to authenticated users
CHM_FEATURE_OPERATIONS_ACCESS=authenticated

## Disable entirely
CHM_FEATURE_OPERATIONS_ENABLED=false
## or
CHM_DISABLED_FEATURES=operations
## CHM_CONFIG_FILE (TOML)
[features.operations]
access = "authenticated"

Configuration

No feature-specific configuration. Global settings apply:

CLICKHOUSE_MAX_EXECUTION_TIME=60
NEXT_QUERY_CACHE_TTL=3600

Notes & limitations

  • system.part_log — requires <part_log> to be enabled in the ClickHouse server config. It is disabled by default on some distributions. If absent, /merge-performance and /part-log show a table-not-found notice.
  • system.moves — only populated when a TTL or storage policy move is actively in progress. The table is empty between moves; this is normal.
  • Kill mutation — the kill-mutation button on /mutations issues KILL MUTATION. The ClickHouse user must have ALTER TABLE privilege (or specifically KILL MUTATION). Without it the action returns an error.
  • Merge progress — system.merges shows only active merges. Completed merges appear in system.part_log with event type MergedPart.
  • The /merges route is also the entry point for the Operations section in the nav (feature id operations).