Create report in scheduled task

Author: MrEricSir

api/README.md

@@ -69,17 +69,38 @@ Web dashboard interface.
 
 ### GET /health
 
-Health check endpoint for monitoring.
+Health check endpoint with component-level status.
 
 **Response** (200 OK):
 ```json
 {
-  "status": "ok",
+  "status": "healthy",
   "service": "muni-status-api",
-  "timestamp": "2025-12-11T23:00:00.000000"
+  "timestamp": "2025-12-11T23:00:00.000000",
+  "components": {
+    "cache": {
+      "status": "healthy",
+      "cache_age_seconds": 45.2,
+      "is_stale": false,
+      "last_status": "green"
+    },
+    "analytics": {
+      "status": "healthy",
+      "total_checks": 20160
+    }
+  }
 }
 ```
 
+**Overall Status Values**:
+- `healthy`: All components working normally
+- `degraded`: Some components have issues but service is functional
+- `unhealthy`: Critical failure (not currently returned as 200)
+
+**Component Status**:
+- `cache`: Status cache freshness (stale if > 5 minutes old)
+- `analytics`: SQLite database connectivity
+
 ### GET /status
 
 Current Muni Metro status with best-of-three smoothing logic.

api/api.py

@@ -173,15 +173,76 @@ def on_get(self, req, resp):
 
 
 class HealthResource:
-    """Health check endpoint."""
+    """Health check endpoint with component status."""
 
     def on_get(self, req, resp):
-        """Handle GET request to /health"""
+        """
+        Handle GET request to /health
+
+        Returns component-level health status:
+        - cache: Status cache freshness
+        - analytics: Analytics database status
+        - overall: Aggregated health (healthy/degraded/unhealthy)
+        """
+        components = {}
+        overall_status = 'healthy'
+
+        # Check status cache
+        try:
+            cache_data = read_cache()
+            if cache_data:
+                cached_at = datetime.fromisoformat(cache_data.get('cached_at', ''))
+                cache_age = (datetime.now() - cached_at).total_seconds()
+                is_stale = cache_age > CACHE_MAX_AGE
+
+                components['cache'] = {
+                    'status': 'degraded' if is_stale else 'healthy',
+                    'cache_age_seconds': round(cache_age, 1),
+                    'is_stale': is_stale,
+                    'last_status': cache_data.get('best_status', {}).get('status')
+                }
+                if is_stale:
+                    overall_status = 'degraded'
+            else:
+                components['cache'] = {
+                    'status': 'unhealthy',
+                    'error': 'No cache data available'
+                }
+                overall_status = 'degraded'
+        except Exception as e:
+            components['cache'] = {
+                'status': 'unhealthy',
+                'error': str(e)
+            }
+            overall_status = 'degraded'
+
+        # Check analytics database
+        try:
+            from lib.analytics import get_db_connection, init_db
+            init_db()  # Ensure tables exist
+            conn = get_db_connection()
+            cursor = conn.cursor()
+            cursor.execute('SELECT COUNT(*) as count FROM status_checks')
+            count = cursor.fetchone()['count']
+            conn.close()
+
+            components['analytics'] = {
+                'status': 'healthy',
+                'total_checks': count
+            }
+        except Exception as e:
+            components['analytics'] = {
+                'status': 'degraded',
+                'error': str(e)
+            }
+            # Analytics failure doesn't affect overall health critically
+
         resp.status = falcon.HTTP_200
         resp.media = {
-            'status': 'ok',
+            'status': overall_status,
             'service': 'muni-status-api',
-            'timestamp': datetime.now().isoformat()
+            'timestamp': datetime.now().isoformat(),
+            'components': components
         }
 
 

api/check_status.py

@@ -7,6 +7,9 @@
     python check_status.py --continuous       # Keep checking every 30 seconds
     python check_status.py --write-cache      # Single check, write to cache
     python check_status.py --continuous --write-cache --interval 60  # Cache mode with custom interval
+    python check_status.py --generate-reports # Generate analytics reports only
+
+In continuous mode with --write-cache, analytics reports are auto-generated at midnight.
 """
 
 import sys
@@ -186,10 +189,37 @@ def check_status(should_write_cache=False):
     return True
 
 
+def generate_analytics_reports():
+    """Generate all analytics reports."""
+    from lib.analytics import generate_all_reports
+
+    print("\nGenerating analytics reports...")
+    try:
+        results = generate_all_reports()
+        for days, result in results.items():
+            if result['success']:
+                print(f"  {days}-day report: {result['total_checks']} checks, {result['delayed_checks']} delays")
+            else:
+                print(f"  {days}-day report: FAILED")
+        return True
+    except Exception as e:
+        print(f"  Error generating reports: {e}")
+        return False
+
+
 def main():
     # Parse arguments
     continuous = '--continuous' in sys.argv or '-c' in sys.argv
     should_write_cache = '--write-cache' in sys.argv
+    generate_reports_only = '--generate-reports' in sys.argv
+
+    # Handle report generation mode
+    if generate_reports_only:
+        print("=" * 60)
+        print("Analytics Report Generator")
+        print("=" * 60)
+        generate_analytics_reports()
+        return
 
     # Parse interval
     interval = DEFAULT_INTERVAL
@@ -220,6 +250,7 @@ def main():
         count = 0
         successful = 0
         failed = 0
+        last_report_hour = -1  # Track when we last generated reports
 
         try:
             while True:
@@ -235,6 +266,12 @@ def main():
 
                 print(f"\nStats: {successful} successful, {failed} failed")
 
+                # Generate analytics reports at midnight (hour 0)
+                current_hour = datetime.now().hour
+                if current_hour == 0 and last_report_hour != 0:
+                    generate_analytics_reports()
+                last_report_hour = current_hour
+
                 if count > 1:
                     print(f"\nWaiting {interval} seconds until next check...")
 

api/generate_reports_job.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""
+Cloud Run Job script for MuniMetro analytics report generation.
+This script is executed by Cloud Scheduler via Cloud Run Jobs (daily at midnight).
+"""
+
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+API_DIR = Path(__file__).resolve().parent
+PROJECT_ROOT = API_DIR.parent
+sys.path.insert(0, str(PROJECT_ROOT))
+
+from lib.analytics import generate_all_reports, init_db
+
+
+def main():
+    """Generate all analytics reports."""
+    try:
+        print("Starting MuniMetro analytics report generation...")
+        print("-" * 60)
+
+        # Ensure database exists
+        init_db()
+
+        # Generate reports for all time periods
+        results = generate_all_reports()
+
+        # Print results
+        all_success = True
+        for days, result in results.items():
+            if result['success']:
+                print(f"  {days}-day report: {result['total_checks']} checks, {result['delayed_checks']} delays")
+            else:
+                print(f"  {days}-day report: FAILED")
+                all_success = False
+
+        if all_success:
+            print("\n✓ All reports generated successfully")
+            sys.exit(0)
+        else:
+            print("\n⚠️ Some reports failed to generate", file=sys.stderr)
+            sys.exit(1)
+
+    except Exception as e:
+        print(f"\n❌ Error during report generation: {e}", file=sys.stderr)
+        import traceback
+        traceback.print_exc()
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

deploy/cloud/README.md

@@ -7,14 +7,15 @@ See [../../CONFIGURATION.md](../../CONFIGURATION.md) for actual deployment confi
 ## Architecture
 
 ```
-Cloud Scheduler (every 3 min)
-  ↓ triggers
-Checker (Cloud Run Job)
-  ↓ downloads image + predicts status
-  ↓ writes JSON + exits
-Cloud Storage (cache file)
-  ↑ reads JSON
-API (Cloud Run Service)
+Cloud Scheduler (every 3 min)          Cloud Scheduler (daily midnight)
+  ↓ triggers                             ↓ triggers
+Checker Job                            Reports Job
+  ↓ downloads image                      ↓ generates analytics
+  ↓ detects status                       ↓ caches reports
+  ↓ writes JSON                          ↓ exits
+Cloud Storage (cache)                  Cloud Storage (reports cache)
+  ↑ reads                                ↑ reads
+API Service  ←───────────────────────────┘
   ↓ serves to users
 Users
 ```
@@ -83,16 +84,17 @@ export MODEL_VERSION=20251223_224331
 
 **Subsequent deploys**: The script automatically uses the currently deployed model version.
 
-### 3. Setup Scheduler
+### 3. Setup Schedulers
 
 ```bash
 ./deploy/cloud/setup-scheduler.sh
 ```
 
-This script:
-- Creates Cloud Scheduler job
-- Configures 3-minute interval
-- Runs test execution
+This script creates two Cloud Scheduler jobs:
+- **Status checker** - Runs every 3 minutes, triggers status detection
+- **Analytics reports** - Runs daily at midnight UTC, generates cached reports
+
+The analytics reports job is isolated from user requests to prevent report generation issues from affecting the main API.
 
 ### 4. Setup Monitoring (Optional but Recommended)
 
@@ -158,15 +160,16 @@ gcloud logging read 'resource.type="cloud_scheduler_job"' --limit 20
 
 ## Cost Estimate
 
-Typical usage costs approximately $1.17/month:
+Typical usage costs approximately $1.20/month:
 
 | Service | Usage | Cost |
 |---------|-------|------|
 | Cloud Run Service (API) | ~1000 requests/day | $0 (free tier) |
-| Cloud Run Jobs (Checker) | 21,600 executions/month @ ~10s each | $1.04 |
-| Cloud Storage | 1KB file, 75K reads/month | $0.016 |
-| Cloud Scheduler | 1 job | $0.10 |
-| **Total** | | **~$1.17/month** |
+| Cloud Run Jobs (Checker) | 14,400 executions/month @ ~10s each | $0.70 |
+| Cloud Run Jobs (Reports) | 30 executions/month @ ~5s each | $0.01 |
+| Cloud Storage | Cache files, ~100K reads/month | $0.02 |
+| Cloud Scheduler | 2 jobs | $0.20 |
+| **Total** | | **~$1.00/month** |
 
 Cloud Run Jobs are more cost-effective than Services for scheduled tasks since execution time is billed without idle costs.