feat: Add health check utility and improve project documentation

Kamal Sai Devarapalli · Kamal Sai Devarapalli · commit eca4f3c39c79 · 2025-12-23T16:41:51.000-07:00
- Add comprehensive health check script for monitoring all microservices
- Add CHANGELOG.md for better project tracking
- Update README with recent improvements and health check usage
- Enhance .gitignore with additional patterns for better dev experience
- Improve code documentation in utility scripts
diff --git a/.gitignore b/.gitignore
@@ -99,3 +99,59 @@ Archive/
 # Test results (keep directory structure but ignore JSON files)
 results/*.json
 !results/README.md
+
+# Bazel
+.bazel/
+bazel-*
+
+# Coverage reports
+.coverage.*
+coverage.xml
+*.cover
+.hypothesis/
+
+# Profiling
+*.prof
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Celery
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env.venv
+.env.*.local
+
+# mkdocs documentation
+/site
+
+# IDEs
+*.sublime-project
+*.sublime-workspace
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+# macOS
+.AppleDouble
+.LSOverride
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to the EventStreamMonitor project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Comprehensive health check utility script for monitoring all services
+- Enhanced documentation with CHANGELOG.md for better project tracking
+- Improved .gitignore patterns for better development experience
+- Better code documentation and type hints in utility scripts
+
+### Improved
+- Enhanced README with better formatting and additional information
+- Improved error handling in test scripts
+- Better service health monitoring capabilities
+
+### Changed
+- Updated project structure documentation
+- Enhanced development workflow documentation
+
+## [1.0.0] - 2024-12-19
+
+### Added
+- Initial release of EventStreamMonitor
+- Real-time microservices monitoring platform
+- Kafka-based event streaming for log processing
+- Live monitoring dashboard with real-time updates
+- Redis caching for performance optimization
+- Database connection pooling optimized for high-throughput workloads
+- Gunicorn-based deployment with multi-worker configuration
+- Docker containerization for all services
+- Service-level error breakdown and statistics
+- Comprehensive test suite
+- Load testing scripts
+- Integration tests for all services
+
+### Services
+- User Management Service (Port 5001)
+- Task Processing Service (Port 5002)
+- Notification Service (Port 5003)
+- Log Monitor Service (Port 5004)
+
+### Documentation
+- Architecture documentation
+- Setup guides for all components
+- Performance configuration guides
+- Bazel build system documentation
+- Contributing guidelines
+
diff --git a/README.md b/README.md
@@ -162,6 +162,9 @@ docker-compose up
 # Run dry run tests
 python3 scripts/dry_run_tests.py
 
+# Run health check
+python3 scripts/health_check.py
+
 # Run integration tests
 cd tests
 python3 -m pytest integration/
@@ -182,6 +185,13 @@ Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTIN
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
+## Recent Updates
+
+- **Enhanced Health Monitoring**: New comprehensive health check utility script
+- **Improved Documentation**: Added CHANGELOG.md for better project tracking
+- **Better Development Experience**: Enhanced .gitignore and development tools
+- **Code Quality**: Improved documentation and type hints across the codebase
+
 ## Acknowledgments
 
 - Apache Kafka for event streaming
@@ -192,3 +202,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 ## Contact
 
 For questions or suggestions, please open an issue on GitHub.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a detailed list of changes and updates.
diff --git a/scripts/health_check.py b/scripts/health_check.py
@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""
+Health Check Utility for EventStreamMonitor Services
+
+This script provides comprehensive health checking for all microservices,
+including connectivity, health endpoints, and service status monitoring.
+"""
+import requests
+import socket
+import time
+import sys
+from typing import Dict, List
+from datetime import datetime
+from dataclasses import dataclass
+
+
+@dataclass
+class ServiceHealth:
+    """Service health status container"""
+    name: str
+    url: str
+    port: int
+    is_reachable: bool
+    is_healthy: bool
+    response_time: float
+    status_code: int = 0
+    error_message: str = ""
+
+
+SERVICES = {
+    "usermanagement": {
+        "url": "http://localhost:5001",
+        "port": 5001,
+        "health_endpoint": "/health",
+        "name": "User Management"
+    },
+    "taskprocessing": {
+        "url": "http://localhost:5002",
+        "port": 5002,
+        "health_endpoint": "/health",
+        "name": "Task Processing"
+    },
+    "notification": {
+        "url": "http://localhost:5003",
+        "port": 5003,
+        "health_endpoint": "/health",
+        "name": "Notification"
+    },
+    "logmonitor": {
+        "url": "http://localhost:5004",
+        "port": 5004,
+        "health_endpoint": "/health",
+        "name": "Log Monitor"
+    }
+}
+
+
+def check_port_connectivity(host: str, port: int, timeout: int = 3) -> bool:
+    """
+    Check if a port is open and accessible
+
+    Args:
+        host: Hostname or IP address
+        port: Port number
+        timeout: Connection timeout in seconds
+
+    Returns:
+        True if port is accessible, False otherwise
+    """
+    try:
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.settimeout(timeout)
+        result = sock.connect_ex((host, port))
+        sock.close()
+        return result == 0
+    except (socket.error, OSError):
+        return False
+
+
+def check_service_health(service_config: Dict) -> ServiceHealth:
+    """
+    Perform comprehensive health check for a service
+
+    Args:
+        service_config: Service configuration dictionary
+
+    Returns:
+        ServiceHealth object with health status
+    """
+    name = service_config.get("name", "Unknown")
+    url = service_config["url"]
+    port = service_config["port"]
+    health_endpoint = service_config.get("health_endpoint", "/health")
+    
+    # Check port connectivity
+    is_reachable = check_port_connectivity("localhost", port)
+    
+    # Check health endpoint
+    is_healthy = False
+    response_time = 0.0
+    status_code = 0
+    error_message = ""
+    
+    if is_reachable:
+        try:
+            start_time = time.time()
+            response = requests.get(
+                f"{url}{health_endpoint}",
+                timeout=5
+            )
+            response_time = (time.time() - start_time) * 1000  # Convert to ms
+            status_code = response.status_code
+            is_healthy = response.status_code == 200
+        except requests.exceptions.Timeout:
+            error_message = "Request timeout"
+        except requests.exceptions.ConnectionError:
+            error_message = "Connection refused"
+        except (requests.exceptions.RequestException, ValueError) as e:
+            error_message = str(e)
+    else:
+        error_message = "Port not accessible"
+    
+    return ServiceHealth(
+        name=name,
+        url=url,
+        port=port,
+        is_reachable=is_reachable,
+        is_healthy=is_healthy,
+        response_time=response_time,
+        status_code=status_code,
+        error_message=error_message
+    )
+
+
+def print_health_status(health: ServiceHealth):
+    """
+    Print formatted health status for a service
+
+    Args:
+        health: ServiceHealth object
+    """
+    status_icon = "✓" if health.is_healthy else "✗"
+    status_text = "HEALTHY" if health.is_healthy else "UNHEALTHY"
+    
+    print(f"\n{status_icon} {health.name}")
+    print(f"  URL: {health.url}")
+    print(f"  Port: {health.port}")
+    print(f"  Status: {status_text}")
+    
+    if health.is_reachable:
+        print(f"  Response Time: {health.response_time:.2f}ms")
+        print(f"  Status Code: {health.status_code}")
+    else:
+        print(f"  Error: {health.error_message}")
+
+
+def main():
+    """Main health check function"""
+    print("=" * 70)
+    print("EVENTSTREAMMONITOR - SERVICE HEALTH CHECK")
+    print("=" * 70)
+    print(f"Timestamp: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    print("=" * 70)
+    
+    health_results: List[ServiceHealth] = []
+    
+    # Check all services
+    for service_config in SERVICES.values():
+        health = check_service_health(service_config)
+        health_results.append(health)
+        print_health_status(health)
+    
+    # Summary
+    print("\n" + "=" * 70)
+    print("SUMMARY")
+    print("=" * 70)
+    
+    healthy_count = sum(1 for h in health_results if h.is_healthy)
+    total_count = len(health_results)
+    
+    print(f"Services Healthy: {healthy_count}/{total_count}")
+    
+    if healthy_count == total_count:
+        print("\n✓ All services are healthy and operational!")
+        return 0
+    else:
+        print("\n✗ Some services are not healthy. Check logs with:")
+        print("  docker-compose logs [service-name]")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+
diff --git a/scripts/quick_stream_errors.py b/scripts/quick_stream_errors.py
@@ -1,7 +1,17 @@
 #!/usr/bin/env python3
 """
-Quick script to stream error events directly to Kafka
-No dependencies on local imports - pure Kafka producer
+Quick script to stream error events directly to Kafka.
+
+This script sends predefined error and critical log events to Kafka for testing
+and demonstration purposes. It connects directly to Kafka without requiring
+local service dependencies.
+
+Usage:
+    python3 scripts/quick_stream_errors.py
+
+Requirements:
+    - Kafka must be running (docker-compose up -d kafka)
+    - kafka-python package installed
 """
 from kafka import KafkaProducer
 import json
@@ -54,7 +64,15 @@
 
 
 def stream_errors():
-    """Stream error events to Kafka"""
+    """
+    Stream predefined error events to Kafka.
+    
+    Connects to Kafka broker, sends error events to the 'application-logs-errors'
+    topic, and provides feedback on the streaming process.
+    
+    Returns:
+        int: Exit code (0 for success, 1 for failure)
+    """
     print("=" * 60)
     print("Streaming Error Events to Kafka")
     print("=" * 60)
