| name | clickhouse-debug-bundle |
| description | Collect ClickHouse diagnostic data — system tables, query logs, merge status,
and server metrics for support tickets and troubleshooting.
Use when investigating persistent issues, preparing debug artifacts,
or collecting evidence for ClickHouse support.
Trigger with "clickhouse debug", "clickhouse diagnostics",
"clickhouse support bundle", "collect clickhouse logs",
"clickhouse system tables".
|
| allowed-tools | Read, Bash(curl:*), Bash(tar:*) |
| version | 1.7.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","database","analytics","clickhouse","olap"] |
| compatibility | Designed for Claude Code |
ClickHouse Debug Bundle
Overview
Collect comprehensive diagnostic data from ClickHouse system.* tables for
troubleshooting performance issues, merge problems, or support escalation. The
skill runs a graduated set of queries — server health, disk and table health,
query performance, and merge/mutation status — then packages the output into a
single artifact you can attach to a support ticket.
Prerequisites
- Access to a ClickHouse server with
SELECT permission on system.* tables
(grant SELECT ON system.* to a restricted user if needed).
- Either
curl (for the HTTP interface, port 8123) or clickhouse-client.
- Connection settings exported as environment variables so no credentials are
hardcoded:
CLICKHOUSE_HOST, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD.
- For deep query-log analysis,
log_queries = 1 must be enabled on the server.
Instructions
Work through the four diagnostic areas below. For an interactive investigation,
run the query for the symptom you are chasing; to produce a full artifact, run
the automated collector in Step 5. The complete query set for every step lives
in references/diagnostic-queries.md.
Step 1: Server health overview
Confirm the server version, uptime, and current-load gauges first — this frames
every later finding.
SELECT
version() AS version,
uptime() AS uptime_seconds,
formatReadableTimeDelta(uptime()) AS uptime_human,
currentDatabase() AS current_db;
Then snapshot system.metrics for the key gauges (Query, Merge,
MemoryTracking, connection counts). Full metric list in the reference.
Step 2: Disk and table health
Find the largest tables and any table under merge pressure (too many active
parts). The full query set covers per-table disk usage, the parts > 100
merge-pressure check, and per-disk free space from system.disks.
