doris-debug
Skill50 starsChanged 13 days agoApache-2.0View on GitHub
Apache Doris production diagnostics router. Use when Apache Doris queries are slow, imports are failing or timing out, compaction is raising -235 errors, nodes are OOM or crashing, materialized views are not rewriting, or tablet/replica health is degraded. Routes to the appropriate doris-debug-* skill. Covers shared-nothing and cloud (storage-compute separation) deployments.
In this repository16 other files it gives its agents.
- develop-with-evidenceSkill
- doris-architecture-advisorSkill
- doris-best-practicesSkill
- doris-debug-cloudSkill
- doris-debug-compactionSkill
- doris-debug-data-lakeSkill
- doris-debug-deploymentSkill
- doris-debug-importSkill
- doris-debug-materialized-viewSkill
- doris-debug-nodeSkill
- doris-debug-querySkill
- doris-debug-resource-isolationSkill
- doris-debug-tabletSkill
- doris-pr-descriptionSkill
- doris-profile-readerSkill
- doris-repo-reviewSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 0 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 17
Read shared/references/01-common-commands.md for diagnostic SQL and API commands.
- Very specific: line 18
Read shared/references/02-source-map.md to map symptoms to Apache Doris source code locations.
- Very specific: line 20
Check shared/references/03-case-index.md for matching production case patterns.
- Very specific: line 58
Stop the bleeding (throttle, kill, reset_rpc_channel) before root cause
- Very specific: line 59
Verify hypotheses against Doris source code (02-source-map.md)
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Doris Debug Router
How to use
- Identify the symptom domain from the table below.
- Read
shared/references/01-common-commands.mdfor diagnostic SQL and API commands. - Read
shared/references/02-source-map.mdto map symptoms to Apache Doris source code locations. - Open the target skill (
<domain>/SKILL.md) and follow its cause table and decision tree. - Check
shared/references/03-case-index.mdfor matching production case patterns.
Skill routing
| Symptom | Skill |
| Slow / timeout / hanging query, Profile analysis, Exchange WaitForData | query/SKILL.md |
| Stream Load / Broker Load / Routine Load failure, Group Commit WAL pile-up | import/SKILL.md |
| -235 / too many versions, compaction score high, compaction lag | compaction/SKILL.md |
| BE/FE OOM, crash, false Alive, memory leak | node/SKILL.md |
| Sync MV miss, async MTMV refresh/rewrite issues | materialized-view/SKILL.md |
| Tablet replica missing, clone backlog, disk skew, tablet repair | tablet/SKILL.md |
| FE/BE startup failure, port conflict, priority_networks misconfig | deployment/SKILL.md |
| Hive/Iceberg/Paimon/Glue catalog query failure, metadata refresh, S3/HDFS connectivity | data-lake/SKILL.md |
| Workload Group queue starvation, CPU/memory isolation leaks, spill issues | resource-isolation/SKILL.md |
| Storage-compute separation, meta-service latency, file cache, warmup | cloud/SKILL.md |
Shared references
| Document | Content |
shared/references/01-common-commands.md | Diagnostic SQL, HTTP API, and CLI commands |
shared/references/02-source-map.md | Symptom → Doris source code mapping (with version annotations) |
shared/references/03-case-index.md | 45 production case summaries across 8 domains |
shared/references/04-metrics-guide.md | Per-domain key metrics with thresholds |
shared/references/05-config-quick-ref.md | Per-domain key configuration parameters with tuning guidance |
shared/guides/ | Cross-module cascade troubleshooting |
Companion skills
doris-profile-reader: Deep Profile analysis for query bottlenecks (referenced byquery/SKILL.mdCause C — BE compute bottleneck).doris-best-practices: Preventive table design and configuration guidance.doris-architecture-advisor: Workload-aware architecture decisions.
Methodology
- Client → FE → BE → Disk/Network top-down investigation
- Logs / Metrics / Profile /
SHOW PROCevidence first - Stop the bleeding (throttle, kill,
reset_rpc_channel) before root cause - Verify hypotheses against Doris source code (
02-source-map.md) - Match known case patterns (
03-case-index.md) to avoid rediscovery
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

