A personal project that automates root-cause classification of Linux server/hardware failures from kernel and system logs — reducing the manual "grep through dmesg and guess" step that normally sits at the start of an incident investigation.
Given a raw kernel/system log (dmesg-style or journalctl-style text), LogRCA:
- Classifies the fault into a subsystem (PCIe, storage/NVMe, GPU,
network, memory) using a two-tier approach:
- Signature matching — regex patterns built from known failure
signatures (e.g.
AER: Link Down detected→ PCIe link failure,NVRM: Xid→ GPU hardware fault). Fast, explainable, and correct for the majority of recurring fleet issues. - TF-IDF similarity fallback — for logs that don't cleanly match a known signature, falls back to comparing the log text against the signature corpus and returns the closest known match with a confidence score, instead of failing to classify at all.
- Signature matching — regex patterns built from known failure
signatures (e.g.
- Generates a structured RCA report — subsystem, plain-English root cause, and a suggested first remediation step, in both human-readable and JSON form.
- Ships with a CI pipeline (
.github/workflows/ci.yml) that runs the test suite and the full diagnostic pipeline on every push — demonstrating the kind of build/test/deploy automation referenced in the JD's CI/CD requirement.
Note: The logs in
data/logs/are synthetic samples I wrote to mimic real dmesg/journalctl output for common failure modes (PCIe AER errors, NVMe controller resets, NVIDIA Xid errors, NIC link flapping, OOM kills) — not logs pulled from a live system.
| Project piece | JD requirement |
|---|---|
| Signature-based log classification | "Perform root cause analysis on hardware failures — correlating across firmware, kernel, driver, and physical layer" |
| Automates fault classification from logs | "Build diagnostic tooling that automates root cause identification and reduces reliance on manual triage" |
| PCIe / NVMe / GPU / NIC fault coverage | "Troubleshoot Linux boot and runtime failures... including PCIe, power, NIC, NVMe, and GPU subsystems" |
| GitHub Actions CI pipeline | "Build, manage, and deploy CI/CD pipelines for rapid deployment of code changes" |
| TF-IDF fallback for unseen faults | Early step toward the "zero-touch operations" goal — degrade gracefully instead of failing to classify |
pip install -r requirements.txt
python -m src.mainOutput:
FILE PREDICTED SUBSYSTEM CONF METHOD
healthy_boot.log healthy none 1.0 keyword-absence ✓
incident_gpu_xid_error.log gpu_xid_error gpu 1.0 signature ✓
incident_nic_link_flap.log nic_link_flap network 1.0 signature ✓
incident_nvme_timeout.log nvme_timeout storage 1.0 signature ✓
incident_oom_kill.log oom_kill memory 1.0 signature ✓
incident_pcie_link_down.log pcie_link_down pcie 1.0 signature ✓
Classification accuracy on sample corpus: 6/6
Run tests:
python tests/test_classifier.py- Add real signature sources (NVIDIA Xid reference table, PCIe AER spec) as a structured, versioned knowledge base instead of inline Python
- Feed classification output into an alerting/ticketing system (e.g. as a webhook) to close the loop toward zero-touch remediation
- Extend the TF-IDF fallback to a proper log-clustering pipeline so new, never-seen fault patterns can be grouped and reviewed in batches
logrca/
├── src/
│ ├── signatures.py # known fault signature knowledge base
│ ├── log_classifier.py # two-tier classification engine
│ ├── rca_engine.py # structured RCA report generation
│ └── main.py # pipeline orchestration
├── tests/
│ └── test_classifier.py
├── data/logs/ # sample synthetic incident logs
├── docs/
│ └── rca_report.json # generated on run
├── .github/workflows/ci.yml # CI pipeline
└── requirements.txt
Chiranjeevi Nadambaram Balaji — Network Engineer linkedin.com/in/balaji-c006