byted-bytehouse-diagnostics

ByteHouse Cluster Diagnostic Skill

🔵 ByteHouse brand identity

"ByteHouse" — Volcengine cloud-native data warehouse, blazing fast, stable, secure, and easy to use

This Skill is based on ByteHouse MCP Server and provides complete cluster diagnostic and health check capabilities

Description

ByteHouse cluster diagnostic and health check tool.

Use this Skill in the following situations: (1) Need to check ByteHouse cluster health status (2) Need to diagnose cluster problems and anomalies (3) Need to view cluster node status (4) Need to analyze cluster performance metrics (5) User mentions "cluster diagnostic", "health check", "node status", "cluster problem"

Prerequisites

Python 3.8+
uv (already installed in /root/.local/bin/uv)
ByteHouse MCP Server Skill - this skill depends on the ByteHouse access capability provided by the bytehouse-mcp skill

Dependencies

This skill depends on the bytehouse-mcp skill and uses the MCP Server it provides to access ByteHouse.

Ensure that the bytehouse-mcp skill is correctly configured and can be used normally.

📁 File description

SKILL.md - This file, the main skill document
cluster_diagnostics.py - Cluster diagnostic main program
README.md - Quick start guide

Configuration information

ByteHouse connection configuration

This skill reuses the configuration of the bytehouse-mcp skill. Please ensure that the following has been configured in the bytehouse-mcp skill:

export BYTEHOUSE_HOST="<ByteHouse-host>"
export BYTEHOUSE_PORT="<ByteHouse-port>"
export BYTEHOUSE_USER="<ByteHouse-user>"
export BYTEHOUSE_PASSWORD="<ByteHouse-password>"
export BYTEHOUSE_SECURE="true"
export BYTEHOUSE_VERIFY="true"

🎯 Features

1. Cluster health check

Check cluster node status
Check replica synchronization status
Check data partition status
Check system table integrity

2. Node status diagnosis

Get cluster node list
Check node liveness status
View node resource usage
Analyze node performance metrics

3. Query history analysis

Query execution history statistics
Slow query identification
Query error analysis
Query performance trends

4. System table check

Check system.parts table
Check system.replicas table
Check system.clusters table
Check system.mutations table

🚀 Quick start

Method 1: Run cluster health check

cd /root/.openclaw/workspace/skills/bytehouse-diagnostics

# 先设置环境变量（复用bytehouse-mcp的配置）
export BYTEHOUSE_HOST="<ByteHouse-host>"
export BYTEHOUSE_PORT="<ByteHouse-port>"
export BYTEHOUSE_USER="<ByteHouse-user>"
export BYTEHOUSE_PASSWORD="<ByteHouse-password>"
export BYTEHOUSE_SECURE="true"
export BYTEHOUSE_VERIFY="true"

# 运行集群诊断
uv run cluster_diagnostics.py

Diagnostic content includes:

Cluster health status
Node status check
Replica synchronization status
Data partition check
Query history analysis
System table integrity check

Output files (saved in the output/ directory):

health_check_{timestamp}.json - Health check report
node_status_{timestamp}.json - Node status report
query_stats_{timestamp}.json - Query statistics report

💻 Diagnostic check items

Health check items

Check item	Description	Status
Cluster connection	Test ByteHouse connectivity	✅/❌
System Table Access	Check whether system.* tables are accessible	✅/❌
Replica Status	Check data replica synchronization status	✅/⚠️/❌
Partition Status	Check data partition integrity	✅/⚠️/❌
Node Liveness	Check cluster node liveness status	✅/❌
Mutation Status	Check mutation execution status	✅/⚠️/❌

Diagnostic Metrics

Cluster Level: Total nodes, active nodes, replica count, partition count
Node Level: CPU usage, memory usage, disk usage, query count
Query Level: Total queries, slow queries, error queries, average query time

📊 Diagnostic Report Example

Health Check Report

{
  "cluster_name": "bh_log_boe",
  "check_time": "2026-03-12T21:00:00",
  "overall_status": "healthy",
  "checks": [
    {
      "name": "cluster_connection",
      "status": "pass",
      "message": "成功连接到ByteHouse"
    }
  ]
}

📚 More Information

For detailed usage instructions, please refer to bytehouse-mcp skill

Last updated: 2026-03-12