skills.rest
netdata
netdataOFFICIAL
Explore all skills by this author →
WebsiteGitHub

troubleshoot-clickhouse

Triage ClickHouse failure archetypes using Netdata MCP metric queries.

1|Updated Apr 17, 2026
Search Tags:#troubleshooting#mcp#observability#performance debugging#clickhouse#netdata#replication lag
One-click install
npx skills add https://github.com/netdata/skills --skill troubleshoot-clickhouse
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: troubleshoot-clickhouse
Source: https://github.com/netdata/skills/tree/main/skills/troubleshoot-clickhouse
Command: npx skills add https://github.com/netdata/skills --skill troubleshoot-clickhouse

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

It helps you triage and diagnose complex ClickHouse incidents—such as merge debt spirals, memory exhaustion, replication lag cascades, ZooKeeper/Keeper saturation, and disk space collapse—by turning Netdata’s collected signals into a structured diagnostic path.

Core Features & Use Cases

  • Failure-mode triage tree: Routes you through the operator playbook’s diagnostic structure mapped to ClickHouse-specific signal domains.
  • MCP-driven signal collection: Queries the right Netdata contexts via MCP for liveness, replication availability, parts/merges activity, insert delays/rejections, and error signals.
  • Actionable verification loop: Re-runs MCP verification queries after remediation to confirm signals return to expected ranges.
  • Use case: An on-call engineer gets paged for a ClickHouse alert and needs a deterministic way to identify the dominant failure archetype and validate remediation.

Quick Start

Use this skill when diagnosing ClickHouse issues by querying Netdata via MCP for the ClickHouse contexts listed in the skill verification section and following the failure archetype decision steps.

Frequently Asked Questions about troubleshoot-clickhouse

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I troubleshoot ClickHouse replication lag and merge debt issues?▼

Troubleshoot ClickHouse replication lag and merge debt by querying Netdata contexts via MCP to rank anomalies, mapping them to domain rule files for structured triage and remediation verification.

Why does ClickHouse experience memory exhaustion and ZooKeeper saturation during incidents?▼

ClickHouse memory exhaustion and ZooKeeper saturation occur from cascading failure archetypes, diagnosed by correlating Netdata metrics for liveness, parts activity, and error signals over a recent window.

What is the best way to diagnose ClickHouse disk space collapse and mutation blocking?▼

The best way to diagnose ClickHouse disk collapse and mutation blocking is applying operator playbook logic to MCP-driven metric queries, matching the failure archetype to a domain rule file for remediation.

Can I use Netdata to verify ClickHouse performance after fixing merge or replication issues?▼

Yes, use Netdata to verify ClickHouse performance by re-running MCP verification queries after remediation, confirming that signals for merges, inserts, and replication lag return to expected ranges.

Does this ClickHouse troubleshooting approach work without ZooKeeper or Keeper dependencies?▼

Yes, the approach handles failure archetypes like memory exhaustion and merge debt independently, but ZooKeeper or Keeper saturation signals are queried when present for complete diagnostic coverage.

What should I do when ClickHouse insert delays and rejections are not working normally?▼

When ClickHouse insert delays or rejections occur, query Netdata contexts for insert activity and error signals to identify the dominant failure archetype and select the matching domain rule for remediation.

Related Skills

Explore More Software Engineering Skills→
netdatanetdata
1

troubleshoot-postgresql

Diagnose PostgreSQL incidents using Netdata MCP queries and structured triage.

Official
Advanced
chmonitorchmonitor
255

incident-response

Triage common ClickHouse operational incidents with diagnostic queries and remediation steps.

Official
Intermediate
netdatanetdata
1

troubleshoot-tomcat

Diagnose Apache Tomcat incidents using Netdata MCP metric queries.

Official
Advanced
AltinityAltinity
16

altinity-expert-clickhouse-replication

Diagnose ClickHouse replication health with SQL scripts against system tables.

Official
Intermediate