Agent skill · data analytics · jeremylongshore
clickhouse-debug-bundle
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".
Why this skill is useful
Adds specific diagnostic queries and automation scripts for ClickHouse that the AI wouldn't reliably generate on its own.
What it needs
Requires curl, tar installed locally. About 3k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
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: CLICKHOUSEHOST, CLICKHOUSEUSER, CLICKHOUSEPASSWORD. For deep query-log analysis, logqueries = 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. 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. Step 3: Query performance analysis Pull the slowest queries, failed queries, and normalized query patterns from system.querylog over the last 24 hours. See the reference for the slow-query, exception, and normalizedqueryhash aggregation queries. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/clickhouse-debug-bundle