SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsbyted-bytehouse-cluster-diagnostics

byted-bytehouse-cluster-diagnostics

Deployment & operations

View repository

Updated 10-15 17:30

About this skill

ByteHouse Cluster Diagnosis Skill

🔵 ByteHouse Brand Logo

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

This Skill is based on ByteHouse Matrix Agent and provides complete cluster diagnosis and health check capabilities

Description

A one-stop tool for ByteHouse cluster diagnosis, health checks, slow query analysis, and load analysis. All diagnostic capabilities are forwarded through scripts/diagnostics.py to ByteHouse Matrix Agent (a diagnostic-specific Agent officially maintained by ByteHouse). The Skill itself does not directly connect to the cluster, execute SQL, or perform local analysis.

Use this Skill in the following situations:

  1. Need to check ByteHouse cluster health status and diagnose cluster issues and anomalies.
  2. Need to identify and analyze slow queries and provide performance optimization suggestions.
  3. Need to analyze load conditions and compute group resource usage (CPU, memory, concurrency, etc.).
  4. Need to analyze query throughput, identify performance bottlenecks, and locate hotspots.
  5. Users mention keywords such as "cluster diagnosis", "health check", "slow query", "query optimization", "performance analysis", "load analysis", "resource usage", "throughput", etc.

Prerequisites

  • Python 3.8+
  • Python dependency:requests(use pip install requests or python3 -m pip install requests）
  • jq（export_config.sh dependency, used to parse JSON configuration. If not installed, you can use brew install jq、sudo apt install jq or sudo yum install jq）
  • Valid ByteHouse cluster connection information (saved in ~/.bytehouse_config.json）

📁 File Description

  • SKILL.md — this file, the main skill document.
  • scripts/diagnostics.py — the main diagnostic program, responsible for forwarding the user's diagnostic questions to ByteHouse Matrix Agent.
  • scripts/export_config.sh — from ~/.bytehouse_config.json load configuration into environment variables (depends on jq）。

🧭 Agent Usage Guide (Important)

When an Agent takes on cluster diagnosis tasks, it schedules this Skill according to the following process:

  1. Confirm configuration readiness：
    • Check whether ~/.bytehouse_config.json exists and contains BYTEHOUSE_HOST and BYTEHOUSE_PASSWORD。
    • If it does not exist or fields are missing, proactively ask the user for connection information, and complete it according to the JSON structure below before executing. You can send ByteHouse Connection Information Retrieval Guide to the user.
    • Load configuration:source scripts/export_config.sh。
  2. Refine the diagnostic question: Based on the user's original question, alert content, and time range (for example, "last 1 hour", "past 24 hours"), assemble a natural language diagnostic question (Chinese is sufficient). Refer to Common Diagnostic Question Examples。
  3. Execute diagnosis：python3 scripts/diagnostics.py "你的诊断问题", pass through Matrix Agent's streaming response.
  4. Failure fallback: If the diagnostic script returns connection errors, timeouts, 401/403, etc., refer to Failure Fallback Suggestions for handling. Do not bypass the script to connect to the cluster or execute SQL on your own.
  5. Prohibit unauthorized operations: This Skill Only allowedto send diagnostic questions via scripts/diagnostics.py ,strictly prohibitedto connect to the ByteHouse cluster yourself to execute SQL or perform local analysis. All analysis and optimization suggestions must come from the results returned by Matrix Agent.

Configuration Instructions

The configuration is saved in ~/.bytehouse_config.json. If the file exists and is non-empty, use the configuration in the file directly; if it does not exist, ask the user for the connection information (you can send this document to the user for reference:https://www.volcengine.com/docs/6517/1121919?lang=zh）。拿到用户提供的信息后，写入 JSON file to avoid repeated inquiries. When the user switches ByteHouse clusters, update this file as well.

{
   "BYTEHOUSE_HOST": "<ByteHouse-host>",
   "BYTEHOUSE_PASSWORD": "<ByteHouse-password>"
}
  • BYTEHOUSE_HOST(host address) and BYTEHOUSE_PASSWORD(password)must be provided by the user。
  • The password is only written to ~/.bytehouse_config.json，Do notecho it in sessions, logs, or additional shell scripts.
  • Load configuration: 
    source scripts/export_config.sh

Usage

# 1. 加载配置
source scripts/export_config.sh

# 2. 执行诊断
python3 scripts/diagnostics.py "你的诊断问题"

Examples of Common Diagnostic Questions

The following are proven diagnostic question templates that easily yield high-quality output. On this basis, the Agent can supplement parameters such as time window, compute group name, database and table names according to the user's needs:

  • Health Check："请对集群做一次整体健康检查，重点检查节点存活、副本延迟、异常任务和错误日志"
  • Slow Query Analysis："帮我识别过去 6 小时内 TOP 10 的慢查询，并给出优化建议"
  • Load & Resources："分析各个计算组过去 24 小时的负载情况，包括 CPU、内存、并发、排队情况"
  • Throughput Analysis："过去 1 小时集群 QPS、失败率、平均响应时间如何？有没有明显下滑或抖动"
  • Hot Table Analysis："看下 tpcds 库里过去 1 天最热的表和查询模式，有哪些可以优化的点"
  • Alert Root Cause Investigation："最近告警显示 warehouse_default CPU 持续超过 85%，帮我分析原因和缓解建议"

Some Suggestions for High-Quality Diagnostic Questions

  • Specify the time window: Things like "the last 1 hour", "the past 24 hours", "today 10:00-12:00" are all fine; the more specific, the better.
  • Name the objects: If the user has already specified the database, table, or compute group, be sure to include them.
  • Ask only one question: Focus on only one topic per diagnosis; splitting multiple requests into multiple calls works better.
  • Chinese is fine: Matrix Agent supports Chinese natural language.
  • Request next-step actions: You can add "and provide optimization suggestions / next troubleshooting directions" to make the output more suitable for operations use.

Fallback Suggestions for Failures

Symptom Handling Method
BYTEHOUSE_HOST not set Guide the user to provide the connection information, write it to ~/.bytehouse_config.json , then retry source scripts/export_config.sh。
401 / 403 or Authorization -related errors Ask the user to confirm whether BYTEHOUSE_PASSWORD is consistent with the cluster; after a password change, update the JSON file accordingly.
Connection timeout / network unreachable Ask the user to confirm whether the network environment they are in can access BYTEHOUSE_HOST(whether the VPC and Endpoint are open).
Matrix Agent returns empty / too short content Try adding the time window and naming the objects before asking again; or switch to a more focused question and retry.
Python error ModuleNotFoundError: requests Prompt the user to execute pip install requests or python3 -m pip install --user requests。
jq not installed Prompt the user to install jqaccording to the prerequisites; as a temporary fallback, you can have the user manually export BYTEHOUSE_HOST=...、export BYTEHOUSE_PASSWORD=...。

Example

# 加载配置
source scripts/export_config.sh

# 计算组负载诊断
python3 scripts/diagnostics.py "检查一下计算组的负载情况，重点看 CPU 和内存"

# 慢查询分析
python3 scripts/diagnostics.py "帮我识别过去 6 小时的 TOP 10 慢查询，并给出优化建议"

# 集群健康检查
python3 scripts/diagnostics.py "对集群做一次整体健康检查，找出潜在风险"