🚀 -> Project on GitHub <-

🏥 Health Monitoring System v1.2 - Feature Overview

📚 Navigation: 🏠 Home 📖 Docs 🏥 Health Monitoring 📊 Dashboard 🚀 Starter

📋 Component Overview

1. System Monitor (system_monitor.py)

Live System Metrics in Real-time

✨ Features:

🎯 Usage:

from core.health import SystemMonitor

monitor = SystemMonitor(update_interval=1.0)
monitor.start()

metrics = monitor.get_latest_metrics()
print(f"CPU: {metrics.cpu_percent}%")

2. Component Health Checker (component_checker.py)

Automatic Health Check of All Components

✨ Features:

🎯 Status Levels:

🎯 Usage:

from core.health import ComponentHealthChecker

checker = ComponentHealthChecker(project_root)
health = checker.check_all()

for name, status in health.items():
    print(f"{name}: {status.status.value}")

3. Performance Tracker (performance_tracker.py)

Detailed Performance Monitoring

✨ Features:

📊 Metrics:

🎯 Usage:

from core.health import PerformanceTracker, PerformanceTimer

tracker = PerformanceTracker()

with PerformanceTimer(tracker, "my_operation"):
    expensive_function()

stats = tracker.get_stats("my_operation")
print(f"P95: {stats.p95_duration_ms}ms")

4. Alert System (alert_system.py)

Intelligent Warning System with Rules

✨ Features:

🚨 Default Rules:

🎯 Usage:

from core.health import AlertSystem

alerts = AlertSystem()

# Register callback
def on_alert(alert):
    print(f"Alert: {alert.message}")

alerts.register_callback(on_alert)

# Check alerts
alerts.check_alerts({
    'system_metrics': metrics,
    'component_health': health
})

5. Rich Dashboard (rich_dashboard.py)

Beautiful Terminal-based Live Display

✨ Features:

🎨 UI Elements:

🎯 Usage:

from core.health import RichHealthDashboard

dashboard = RichHealthDashboard(project_root)
dashboard.start()  # Blocks until Ctrl+C

6. Integration Helpers (integration.py)

Easy Integration into Existing Code

✨ Features:

🎯 Decorator Example:

from core.health import monitored

@monitored("llm_query")
def generate_response(prompt):
    return llm.generate(prompt)

🎯 Context Manager:

from core.health import HealthMonitoringContext

with HealthMonitoringContext() as monitor:
    # Your code here
    monitor.check_alerts()

🎯 Pre-wrapped Components:

from core.health import create_monitored_llm_client

client = create_monitored_llm_client("config.json")
# All calls are automatically tracked

🚀 Quick Start Scenarios

Scenario 1: Start Monitoring Immediately

# Terminal dashboard
python health-monitor.py

# Or with batch/shell
health-monitor.bat     # Windows
./health-monitor.sh    # Linux/Mac

Scenario 2: Test Dashboard for Development

python health-dashboard.py

Scenario 3: Integration in Your Code

# Minimal integration
from core.health import monitored, print_health_summary
import atexit

@monitored("main_task")
def main():
    pass

atexit.register(print_health_summary)

Scenario 4: Full Integration

from core.health import (
    SystemMonitor,
    PerformanceTracker,
    AlertSystem,
    HealthMonitoringContext
)

class MyApp:
    def __init__(self):
        self.monitor = SystemMonitor()
        self.monitor.start()

    def run(self):
        with HealthMonitoringContext() as health:
            # Your app logic
            pass

📊 Example Dashboard Output

╔══════════════════════════════════════════════════════════╗
║ 🦙 CrawlLama Health Dashboard | 2025-10-24 14:30:00     ║
╚══════════════════════════════════════════════════════════╝

┌─────────────────────────┬─────────────────────────┐
│ 📊 System Metrics       │ 📈 Performance          │
│                         │                         │
│ CPU      45.2%  ████░░  │ llm_query   1250ms  ✓  │
│ Memory   62.1%  ██████░ │ web_search   850ms  ✓  │
│ Disk     38.5%  ███░░░  │ cache_read    25ms  ✓  │
│ Network  ↓1.2/↑0.3 MB/s │                         │
├─────────────────────────┤                         │
│ 🔍 Component Health     │                         │
│                         │                         │
│ LLM Client      ✓ 45ms  │                         │
│ Cache System    ✓ 12ms  │                         │
│ RAG System      ✓ 89ms  │                         │
│ Search Tools    ✓ 23ms  │                         │
└─────────────────────────┴─────────────────────────┘
┌─────────────────────────────────────────────────────┐
│ 🚨 Alerts (2)                                        │
│                                                      │
│ 🟡 High CPU usage: 87.5% (threshold: 85.0%)        │
│ 🟠 Slow operations: llm_query (P95: 5200ms)        │
└─────────────────────────────────────────────────────┘

Alerts: 🔴 0 🟠 1 🟡 1 | Press Ctrl+C to exit

📈 Performance Metrics Interpretation

Response Time Guideline

Throughput Guideline

Success Rate

🔧 Configuration & Customization

Adjust Alert Thresholds

from core.health import AlertSystem, CPUAlertRule, AlertLevel

alerts = AlertSystem()
alerts.rules.clear()  # Remove default rules

# Add custom rule
alerts.add_rule(CPUAlertRule(
    threshold=70.0,
    level=AlertLevel.WARNING
))

Adjust Performance Tracking Window

from core.health import PerformanceTracker

tracker = PerformanceTracker(
    max_history=2000,      # Keep 2000 entries
    window_minutes=30      # 30-minute window for throughput
)

Adjust System Monitor Interval

from core.health import SystemMonitor

monitor = SystemMonitor(update_interval=0.5)  # 0.5s updates

📦 Dependencies

All already in requirements.txt:

No additional installation needed!

🐛 Troubleshooting

Problem: “No module named ‘rich’”

Solution: pip install rich psutil

Problem: Dashboard shows no metrics

Solution: Wait 1-2 seconds after start for first metrics

Problem: Component checks fail

Solution:

  1. Check config.json
  2. Create missing directories: mkdir -p data/cache data/embeddings

Problem: Performance data missing

Solution: Integrate @monitored decorator in your code

🎯 Best Practices

  1. Start System Monitor Early: In __init__ or main()
  2. Use Decorators: Easiest integration
  3. Register Alert Callbacks: For logging/notifications
  4. Check Health Periodically: Every 30-60 seconds
  5. Export Metrics: For historical analysis
  6. Adjust Thresholds: Based on your environment
  7. Monitor Critical Paths: LLM, Search, RAG
  8. Use Context Manager: For temporary monitoring

📚 Documentation

✨ Version History

v1.2.0 (2025-10-24)

Made with ❤️ for CrawlLama v1.2