Specialized knowledge for the ClickHouse Monitor dashboard. Use this skill when: working with ClickHouse monitoring dashboards, analyzing query performance, writing ClickHouse system table queries, developing dashboard features, or integrating with the ClickHouse Monitor API. Covers query monitoring, table management, merge operations, system metrics, and ClickHouse version compatibility.
How this skill is triggered — by the user, by Claude, or both
Slash command
/clickhouse-monitoring:clickhouse-monitoringThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Real-time monitoring and observability dashboard for ClickHouse clusters. Static site architecture with client-side SWR data fetching, multi-host support, and version-aware queries.
Real-time monitoring and observability dashboard for ClickHouse clusters. Static site architecture with client-side SWR data fetching, multi-host support, and version-aware queries.
Navigate using query parameter routing (?host=N for multi-host setups):
/overview?host=0 - System overview (Connections, Queries, Merges, Replication, System)/running-queries?host=0 - Active queries with progress tracking/explorer?host=0 - Interactive database schema browser/merges?host=0 - Active merge operations with progress/clusters?host=0 - Cluster configuration and ZooKeeper statusConfigure multiple ClickHouse instances via comma-separated environment variables:
CLICKHOUSE_HOST=prod.example.com,staging.example.com
CLICKHOUSE_USER=admin,readonly
CLICKHOUSE_PASSWORD=secret,readonly_secret
CLICKHOUSE_NAME="Production,Staging"
Access hosts via ?host=0, ?host=1, etc. in URLs.
Track query performance and resource usage:
Browse database objects and metadata:
Monitor background MergeTree activity:
Real-time server monitoring:
Track security events and system logs:
Fetch time-series data for visualization:
GET /api/v1/charts/{chartName}?hostId={hostId}&interval={interval}&lastHours={hours}
Parameters:
chartName - Name from chart registry (see references for full list)hostId - Host index (0-based)interval - Time bucket: 1m, 5m, 1h, 1dlastHours - Historical range (default: 24)Response:
{
"success": true,
"data": [{ "ts": "2026-03-05T00:00:00Z", "value": 1234 }],
"metadata": {
"queryId": "abc123",
"duration": 45,
"rows": 24,
"host": "clickhouse.example.com",
"clickhouseVersion": "24.3.1.1"
}
}
Fetch paginated table data:
GET /api/v1/tables/{queryConfigName}?hostId={hostId}&pageSize={n}&page={p}
Supports sorting (sortCol, sortOrder) and filtering per query config.
Browse schema structure:
GET /api/v1/explorer/databases?hostId={hostId}
GET /api/v1/explorer/tables?hostId={hostId}&database={db}
GET /api/v1/explorer/columns?hostId={hostId}&database={db}&table={t}
CRITICAL: Fully static site with client-side data fetching. No SSR, no middleware.
Routing Pattern:
// Static route with query parameter
app/overview/page.tsx → /overview?host=0
// NOT dynamic routes (deprecated)
// app/[host]/overview/page.tsx
Page Component Template:
'use client'
import { Suspense } from 'react'
import { useHostId } from '@/lib/swr'
import { ChartSkeleton } from '@/components/skeletons'
import { YourChart } from '@/components/charts/your-chart'
export default function YourPage() {
const hostId = useHostId() // Extracts from ?host= query param
return (
<Suspense fallback={<ChartSkeleton />}>
<YourChart hostId={hostId} />
</Suspense>
)
}
All data uses SWR with the hostId pattern:
import useSWR from 'swr'
import { useChartData } from '@/lib/swr/use-chart-data'
export function YourChart({ hostId }: { hostId: number }) {
const { data, error, isLoading } = useChartData({
name: 'your-chart-name',
hostId,
interval: 300000, // 5 minutes SWR cache
})
if (isLoading) return <ChartSkeleton />
if (error) return <ChartError error={error} />
// ... render chart with data
}
lib/api/charts/{domain}-charts.ts:export const yourChart: ChartQueryBuilder = (params) => ({
sql: `
SELECT toStartOfInterval(event_time, INTERVAL {interval:UInt64} SECOND) AS ts,
COUNT() AS value
FROM system.query_log
WHERE event_time > now() - INTERVAL {lastHours:UInt64} HOUR
GROUP BY ts ORDER BY ts
`,
columns: ['ts', 'value'],
})
lib/api/chart-registry.ts:export const chartRegistry = {
// ...
'your-chart-name': yourChart,
}
components/charts/:'use client'
import { useChartData } from '@/lib/swr/use-chart-data'
export function YourChart({ hostId }: { hostId: number }) {
const { data } = useChartData({ name: 'your-chart-name', hostId })
// Render using Recharts or Tremor
}
Add table views via QueryConfig in lib/query-config/queries/:
export const yourConfig: QueryConfig = {
name: 'your-query',
description: 'Query description',
sql: `
SELECT database, table,
formatReadableQuantity(sum(rows)) AS total_rows
FROM system.parts
WHERE active
GROUP BY database, table
ORDER BY total_rows DESC
`,
columns: ['database', 'table', 'total_rows'],
columnFormats: {
database: ColumnFormat.Badge,
total_rows: [ColumnFormat.BackgroundBar, {
base: 'rows',
readable: 'total_rows',
pct: 'pct_rows'
}],
},
}
BackgroundBar format requires 3 SQL columns:
rows, -- base value
formatReadableQuantity(rows) AS total_rows, -- display
round(rows * 100 / max(rows) OVER (), 2) AS pct_rows -- percentage
ClickHouse system tables change between versions. Use VersionedSql[]:
export const yourConfig: QueryConfig = {
name: 'your-query',
sql: [
{ since: '23.8', sql: 'SELECT col1 FROM system.table' },
{ since: '24.3', sql: 'SELECT col1, col2 FROM system.table' },
],
columns: ['col1', 'col2'],
}
The system selects the appropriate query based on detected ClickHouse version.
Some tables don't exist depending on configuration. Mark as optional:
export const backupsConfig: QueryConfig = {
name: 'backups',
optional: true, // Graceful handling if table missing
tableCheck: 'system.backup_log',
sql: 'SELECT * FROM system.backup_log',
// ...
}
Optional tables: backup_log, error_log, zookeeper, monitoring_events.
Empty charts?
query_log, metric_log, part_logdocs/clickhouse-schemas/ for table requirementsAPI returns table_not_found?
docs/clickhouse-schemas/tables/{table}.mdMulti-host not working?
host1,host2 (not spaces)This skill documentation is synced from the main clickhouse-monitor repository. Run bun run scripts/sync-docs.ts to update.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub duyet/codex-claude-plugins --plugin clickhouse-monitoring