clickhouse-debug-bundle

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 <[e-mail]>
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.

-- Tables with too many parts (merge pressure)
 database, , ()  parts
 system.parts  active
  database, 
 parts  
  parts ;