🚀 -> 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