SOS Report Analyzer is a comprehensive Python-based tool designed to automatically analyze Linux SOS reports, with a focus on identifying storage-related issues. It provides both command-line analysis and an interactive web dashboard for visualizing findings, along with advanced ML-powered insights, trend analysis, performance metrics, and automated report generation.
Perfect for:
- 🔧 System Administrators - Quickly identify storage issues and predict failures
- 🏢 Enterprise Support Teams - Streamline analysis with ML prioritization
- 📊 DevOps Engineers - Track system health trends over time
- 🎓 RHEL Learning - Understand common storage issues and patterns
- 🔮 Proactive Monitoring - Predict failures before they occur
| Component | What It Analyzes |
|---|---|
| 💾 Disk & Block Devices | I/O errors, SMART failures, reallocated sectors, capacity, timeouts |
| 📁 Filesystems | Mount issues, XFS/EXT errors, NFS problems, inode usage, corruption |
| 🗂️ LVM | PV/VG/LV status, thin pool capacity, missing volumes, inactive LVs |
| 🔄 Multipath | Failed paths, redundancy loss, configuration issues |
| 💿 RAID (MD) | Degraded arrays, failed devices, rebuild status |
| 🐙 Ceph Cluster | OSD status, placement groups, monitor quorum, cluster health |
- Real-time Analysis - Analyze SOS reports through web interface
- Tabbed Interface - Organized views for Overview, Findings, Trends, Performance, ML Insights, Reports
- Visual Charts - Severity distribution and category breakdowns with Plotly
- Smart Filtering - Filter by severity level and component category
- Export Options - Download results as JSON or CSV
- Historical Analysis - Load and compare previous analysis results
- ✅ Python 3.14 Compatible - Custom tar extraction filter for latest Python
- ✅ Automatic Permission Fixing - Handles SOS reports with restrictive permissions
- ✅ Severity-Based Prioritization - CRITICAL, HIGH, MEDIUM, LOW, INFO levels
- ✅ Actionable Recommendations - Specific fix suggestions for each finding
- ✅ Extensible Architecture - Easy to add new analyzers and checks
Track issues across multiple SOS reports over time to identify patterns and recurring problems.
Features:
- Historical tracking of findings across analyses
- Severity trend visualization
- Category-based trend analysis
- Recurring issue identification with frequency tracking
- Pattern detection (increasing/degrading/stable trends)
- Statistical analysis (mean, min, max values)
Usage:
from trend_analyzer import TrendAnalyzer
analyzer = TrendAnalyzer()
summary = analyzer.get_summary()
patterns = analyzer.detect_patterns()
recurring = analyzer.get_recurring_issues()Calculate system health scores and track performance over time.
Features:
- Health score calculation (0-100 scale)
- Risk level assessment (LOW, MEDIUM, HIGH, CRITICAL)
- Category-specific health scoring
- Performance benchmarking against historical baselines
- Trend detection (improving/degrading/stable)
- Deviation analysis from averages
Health Score Thresholds:
- 90-100: LOW risk (✅ Healthy)
- 70-89: MEDIUM risk (
⚠️ Monitor) - 50-69: HIGH risk (🔶 Action needed)
- 0-49: CRITICAL risk (🔴 Urgent)
Usage:
from performance_metrics import PerformanceMetrics
metrics = PerformanceMetrics()
health_score = metrics.calculate_health_score(findings)
summary = metrics.get_performance_summary()
benchmark = metrics.generate_benchmark_report()ML-powered anomaly detection, failure prediction, and intelligent prioritization.
Features:
-
Anomaly Detection: Identifies unusual patterns based on historical data
- Unusual findings count detection (z-score analysis)
- Abnormal severity distribution detection
- New category identification
- Rare issue pattern recognition
-
Failure Prediction: Predicts potential system failures
- Storage failure prediction (24-48 hour timeframe)
- Ceph cluster degradation prediction
- Capacity exhaustion forecasting
- Performance degradation alerts
-
Intelligent Prioritization: ML-driven issue ranking
- Severity-weighted scoring (0-200+ scale)
- Storage-critical issue boosting
- Ceph component priority weighting
- Recurring issue identification
- Capacity-related escalation
Usage:
from ml_analyzer import MLAnalyzer
ml = MLAnalyzer()
anomalies = ml.detect_anomalies(findings)
predictions = ml.predict_failures(findings)
prioritized = ml.prioritize_issues(findings)
insights = ml.get_ml_insights(findings)Generate professional reports in multiple formats with executive summaries.
Features:
- HTML Reports: Beautiful, responsive reports with styling
- PDF Reports: Professional PDF generation (requires weasyprint)
- Text Reports: Plain text for email/logs
- Executive Summaries: Auto-generated high-level overviews
- Recommendations: Category-specific actionable recommendations
- Visual Metrics: Severity badges, color coding, metrics dashboard
Usage:
# Command line
python analyzer.py /path/to/sosreport.tar.xz results.json --report-format html
python analyzer.py /path/to/sosreport.tar.xz results.json --report-format pdf
# Python API
from reports_generator import ReportGenerator
generator = ReportGenerator()
generator.generate_html_report(findings, "report.html")
generator.generate_pdf_report(findings, "report.pdf")
generator.generate_text_report(findings, "report.txt")- Python 3.7 or higher
- pip (Python package manager)
# Clone the repository
git clone https://github.com/Abhinav0002/sos_analyzer.git
cd sos_analyzer
# Install dependencies
pip install -r requirements.txt
# Verify installation
python verify_install.pyOption 1: Command Line Analysis
# Basic analysis
python analyzer.py /path/to/sosreport.tar.xz results.json
# With HTML report
python analyzer.py /path/to/sosreport.tar.xz results.json --report-format html
# With PDF report
python analyzer.py /path/to/sosreport.tar.xz results.json --report-format pdfOption 2: Interactive Dashboard
./run_dashboard.shThen open your browser to http://localhost:8501
Dashboard Tabs:
- 📊 Overview - Summary, health score, risk level, charts
- 🔍 Findings - Detailed issues with filtering
- 📈 Trends - Historical patterns and recurring issues
- ⚡ Performance - Health scores and benchmarks
- 🤖 ML Insights - Anomalies, predictions, prioritization
- 📄 Reports - Generate HTML/PDF/Text reports
- QUICKSTART.md - Quick start guide for new users
- INSTALL.md - Detailed installation instructions
- ARCHITECTURE.md - System design and architecture
- CONTRIBUTING.md - Contribution guidelines
- CHANGELOG.md - Version history
ANALYSIS SUMMARY
==============================================================
Hostname: ceph-node1
Total Findings: 12
Health Score: 65/100
Risk Level: HIGH
Severity Breakdown:
CRITICAL: 2
HIGH: 4
MEDIUM: 4
LOW: 2
Advanced Analysis:
⚠️ Anomalies Detected: 3 (Anomaly Score: 8.5)
⚠️ Failure Predictions: 1 (Storage failure - HIGH probability)
CRITICAL ISSUES:
1. Disk /dev/sda Usage Critical
Category: Disk
Usage at 98% - immediate action required
Recommendation: Expand storage or cleanup data
The analyzer detects hundreds of specific issues across categories:
Disk Issues:
- High disk usage (>85%, >95%)
- I/O errors and timeouts
- SMART failures
- Reallocated sectors
- Device timeouts
Filesystem Issues:
- Mount failures
- XFS corruption
- Read-only filesystems
- Inode exhaustion
- NFS stale handles
LVM Issues:
- Thin pool high usage (>75%, >90%)
- Missing PVs
- Inactive LVs
- Failed volume groups
Ceph Issues:
- OSD down/out
- Degraded placement groups
- Monitor quorum issues
- Cluster capacity warnings
- Health errors
...and many more!
┌─────────┐ ┌──────────┐ ┌──────────┐
│ SOS │───▶│ Parser │───▶│ Analyzer │
│ Report │ │ Extract │ │ Engine │
└─────────┘ └──────────┘ └────┬─────┘
│
┌────────────────┼────────────────┐
│ │ │
┌─────▼─────┐ ┌────▼─────┐ ┌─────▼─────┐
│ Core │ │ Advanced │ │ Dashboard │
│ Analyzers │ │ Features │ │ UI │
├───────────┤ ├──────────┤ ├───────────┤
│ • Disk │ │ • Trend │ │ • Charts │
│ • FS │ │ • ML │ │ • Filter │
│ • LVM │ │ • Perf │ │ • Export │
│ • MPATH │ │ • Report │ │ • Trends │
│ • RAID │ │ • Pred. │ │ • ML View │
│ • Ceph │ └──────────┘ └───────────┘
└───────────┘
- SOSParser - Extracts and parses SOS report archives
- BaseAnalyzer - Abstract framework for all analyzers
- Specialized Analyzers - Domain-specific storage checks
- SOSAnalyzer - Main orchestrator coordinating analysis
- TrendAnalyzer - Historical pattern tracking
- PerformanceMetrics - Health scoring and benchmarking
- MLAnalyzer - Anomaly detection and predictions
- ReportGenerator - Professional report generation
- Dashboard - Streamlit web interface with advanced features
Adding a new analyzer is straightforward:
# analyzers/iscsi_analyzer.py
from .base_analyzer import BaseAnalyzer
class ISCSIAnalyzer(BaseAnalyzer):
def analyze(self):
self.findings = []
# Your analysis logic
self.add_finding(
severity='HIGH',
category='iSCSI',
title='iSCSI connection timeout',
description='Found timeout errors in iSCSI logs',
affected_resources=['iqn.2020-01.com.example:target1'],
recommendation='Check network connectivity to iSCSI target'
)
return self.findingsThen register in analyzer.py:
from analyzers.iscsi_analyzer import ISCSIAnalyzer
analyzers = [
# ... existing analyzers
ISCSIAnalyzer(self.parser),
]Analysis summary with health score, risk level, and visual charts showing severity distribution
Trend analysis with historical charts, ML insights with anomaly detection, and automated report generation
Anomaly detection, failure predictions, and intelligent issue prioritization
📸 Screenshots available in
/docs/screenshots/
sos_analyzer/
├── analyzer.py # Main orchestrator with advanced features
├── requirements.txt # Python dependencies
├── run_dashboard.sh # Dashboard launcher
├── cleanup_extracted.sh # Cleanup utility
├── verify_install.py # Installation checker
├── test_advanced_features.py # Test suite for advanced features
│
├── utils/
│ └── sos_parser.py # SOS report extraction & parsing
│
├── analyzers/
│ ├── base_analyzer.py # Abstract base class
│ ├── disk_analyzer.py # Disk & block device checks
│ ├── filesystem_analyzer.py # Filesystem health checks
│ ├── lvm_analyzer.py # LVM status monitoring
│ ├── multipath_analyzer.py # Multipath configuration
│ ├── raid_analyzer.py # RAID array status
│ └── ceph_analyzer.py # Ceph cluster analysis
│
├── dashboard/
│ └── app.py # Streamlit web interface with advanced UI
│
├── trend_analyzer.py # Historical trend analysis
├── reports_generator.py # Report generation (HTML/PDF/Text)
├── performance_metrics.py # Health scoring and metrics
└── ml_analyzer.py # ML-based insights and predictions
# Verify installation
python verify_install.py
# Test advanced features
python test_advanced_features.py
# Test with sample SOS report
python analyzer.py /path/to/sample-sosreport.tar.xz test.json
# Launch dashboard in dev mode
streamlit run dashboard/app.py --server.runOnSave trueThis project uses:
- Black for code formatting
- Conventional Commits for commit messages
- Type hints for better code clarity
Contributions are welcome! Here's how you can help:
- 🔍 New Analyzers - iSCSI, GlusterFS, NVMe, performance metrics
- 📊 Enhanced Visualizations - More chart types, 3D visualizations
- 🐛 Bug Fixes - Report issues and submit fixes
- 📝 Documentation - Improve guides, add examples
- 🧪 Test Coverage - Add unit and integration tests
- 🤖 ML Improvements - Better models, more predictions
- 📈 Trend Analysis - Advanced pattern detection
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-analyzer) - Make your changes
- Test thoroughly
- Commit using conventional commits (
feat:,fix:,docs:) - Push to your fork
- Open a Pull Request
| Level | Icon | Meaning | Action Required |
|---|---|---|---|
| CRITICAL | 🔴 | Data loss risk, system down | Immediate action required |
| HIGH | 🟠 | Serious issue, no redundancy | Address ASAP |
| MEDIUM | 🟡 | Issue present, plan needed | Schedule fix |
| LOW | 🟢 | Minor issue, optimization | Address when convenient |
| INFO | 🔵 | Informational, FYI | No action needed |
- OS: Linux, macOS, or Windows
- Python: 3.7 or higher
- Memory: 2GB minimum (4GB recommended for large SOS reports)
- Disk: 500MB for dependencies + space for SOS reports
streamlit # Web dashboard framework
pandas # Data manipulation
plotly # Interactive visualizations
python-dateutil # Date parsing
tabulate # Table formatting
weasyprint # PDF report generation
By default, SOS reports are extracted to sos_analyzer/sos_extracted/
To change:
parser = SOSParser(sos_path)
parser.extract(extract_dir="/custom/path")Enable/disable advanced features:
analyzer = SOSAnalyzer(sos_path, enable_advanced_features=True)Remove extracted files:
./cleanup_extracted.shIssue: Permission denied errors during extraction
# Solution: The analyzer automatically fixes permissions
# If issues persist, manually fix:
chmod -R u+rwX sos_extracted/Issue: Dashboard won't start
# Check if streamlit is installed
pip install -r requirements.txt
# Try different port
streamlit run dashboard/app.py --server.port 8502Issue: Python version too old
# Check version
python3 --version
# Install Python 3.7+ from python.org or use:
brew install python@3.9 # macOS
sudo apt install python3.9 # Ubuntu/DebianIssue: PDF generation fails
# Install weasyprint dependencies
# Ubuntu/Debian:
sudo apt-get install python3-cffi python3-brotli libpango-1.0-0 libpangoft2-1.0-0
# macOS:
brew install pango
pip install weasyprintThis project is licensed under the MIT License - see the LICENSE file for details.
- Built with Streamlit for the dashboard
- Uses Plotly for interactive visualizations
- PDF generation powered by WeasyPrint
- Inspired by the need for faster RHEL storage issue diagnosis
- Thanks to all contributors and the open-source community
- 🐛 Bug Reports: Open an issue
- 💡 Feature Requests: Open an issue
- 📧 Questions: Check QUICKSTART.md or open a discussion
- Trend Analysis - Historical tracking and pattern detection
- Auto-generated Reports - PDF/HTML/Text report generation
- Performance Metrics - Health scoring and benchmarking
- Machine Learning - Anomaly detection and failure prediction
- Ceph Analyzer - Comprehensive Ceph cluster analysis
- Advanced Dashboard - Tabbed UI with ML insights
- iSCSI Analyzer - Detect iSCSI configuration issues
- Email Alerts - Send notifications for critical findings
- REST API - HTTP API for integration
- GlusterFS Analyzer - Distributed filesystem analysis
- Network Analysis - Bond, bridge, VLAN configuration
- Performance Correlation - Link issues to performance impacts
- Multi-report Comparison - Side-by-side report comparison
Made with ❤️ for RHEL System Administrators
⭐ Star this repo if you find it useful!