_private/qwestly-docs/Engineering/Monitoring/status-dashboard.md

Table of Contents

Status Dashboard

The Qwestly Status Dashboard is a React-based real-time monitoring interface that provides operations teams with comprehensive visibility into system health and operational metrics.

Overview

URL: https://qwestly-status.vercel.app / https://status.qwestly.com Repository: /qwestly-monitoring/qwestly-status/
Technology: React 19, Vite, TailwindCSS, Tanstack React Query

Features

Real-time System Monitoring

  • System Health Score: Calculated from CPU, memory, and disk usage
  • Resource Metrics: Live CPU, memory, and disk utilization
  • Environment Status: Validation of required configuration variables
  • Deployment Tracking: Days since deployment and system uptime

Log Shipping Management

  • Daily Log Status: Visual indicators for auth, postgres, and API logs
  • Manual Triggers: One-click log shipping initiation
  • Historical View: Recent log shipping history and patterns
  • Missing Date Detection: Alerts for gaps in log collection
  • Storage Analytics: Log file sizes and entry counts

User Experience

  • Auto-refresh: Updates every 30-60 seconds automatically
  • Manual Refresh: Force refresh individual components
  • Responsive Design: Optimized for desktop, tablet, and mobile
  • Error Boundaries: Graceful error handling with recovery options
  • Loading States: Smooth loading indicators and skeleton screens

Dashboard Components

  • Service status and version information
  • Global refresh controls
  • Real-time operational status badges

System Overview

  • Quick statistics grid with key metrics
  • Health score calculation and status indicators
  • System status summary with visual indicators
  • Quick action buttons for common tasks

System Health Detail

  • CPU usage with threshold-based color coding
  • Memory usage and available memory tracking
  • Disk usage and free space monitoring
  • Environment variable validation results

Log Status Detail

  • Deployment information and timeline
  • Recent log status by date and type
  • Yesterday's log statistics with sizes
  • Manual log shipping controls
  • Full report toggle with detailed information

Health Thresholds

Metric Warning Critical
CPU Usage 80% 90%
Memory Usage 80% 90%
Disk Usage 80% 90%

Status Indicators

Status Color Meaning
Healthy Green All systems operating normally
Warning Yellow Some metrics approaching thresholds
Error Red Critical issues requiring attention
Unknown Gray Unable to determine status

API Integration

The dashboard connects to the Monitoring API via the VITE_API_URL environment variable.

Key API Endpoints Used

  • GET /api/health - System health metrics
  • GET /api/logs/status - Log shipping status
  • GET /api/logs/report - Detailed log reports
  • POST /api/logs/ship - Manual log shipping trigger

Error Handling

  • Network Failures: Automatic retry with exponential backoff
  • API Errors: User-friendly error messages with recovery suggestions
  • CORS Issues: Handled via backend configuration
  • Timeout Handling: 10-second request timeout with user feedback

Development

Local Setup

cd /Users/dominick/Work/qwestly-workspace/qwestly-monitoring
npm run dev:frontend

Environment Variables

# qwestly-status/.env
VITE_API_URL=https://qwestly-monitoring-api.vercel.app

Build Process

# Production build
npm run build:frontend

# Preview build locally
cd qwestly-status && npm run preview

Deployment

Production Deployment

The dashboard is deployed as a static site to Vercel with automatic deployments from the main branch.

Deployment URL: https://qwestly-status.vercel.app

Environment Configuration

Set VITE_API_URL in Vercel dashboard to point to the production monitoring API.

Deployment Process

  1. Code changes pushed to repository
  2. Automatic build triggered on Vercel
  3. Static files generated and deployed
  4. CDN cache updated globally

Performance

Optimization Features

  • Code Splitting: Automatic bundle splitting by Vite
  • Tree Shaking: Unused code elimination
  • Asset Optimization: Minified CSS/JS and optimized images
  • Caching: Intelligent caching with React Query
  • Bundle Size: < 500KB gzipped total

Loading Performance

  • First Contentful Paint: < 1.5s
  • Time to Interactive: < 2.5s
  • Cumulative Layout Shift: < 0.1

Security

Access Control

  • Internal Use: Designed for internal operations team
  • Network Security: Should be accessed behind VPN or internal network
  • No Authentication: Currently open access (internal tool)

Data Security

  • No Sensitive Data Storage: All data fetched from API in real-time
  • HTTPS Only: All communications encrypted in transit
  • Environment Variables: Secure configuration management

Monitoring & Analytics

Error Tracking

  • Error Boundaries: Catch and report React component errors
  • Console Logging: Development and debugging information
  • Network Monitoring: API call success/failure tracking

Usage Analytics

  • Performance Metrics: Core Web Vitals tracking
  • User Experience: Error rates and recovery success
  • API Health: Response times and success rates

Troubleshooting

Common Issues

Dashboard won't load:

  1. Check API URL configuration
  2. Verify backend API is operational
  3. Check browser console for errors
  4. Test API endpoints directly

Data not updating:

  1. Check auto-refresh functionality
  2. Use manual refresh button
  3. Verify API connectivity
  4. Check backend system health

CORS errors:

  1. Verify VITE_API_URL environment variable
  2. Check backend CORS configuration
  3. Ensure API allows dashboard domain

Debug Tools

Browser Console:

// Test API connectivity
fetch('https://qwestly-monitoring-api.vercel.app/api/health')
  .then(r => r.json())
  .then(console.log)

// Check environment variables
console.log('API URL:', import.meta.env.VITE_API_URL)

Network Tab:

  • Monitor API request/response cycles
  • Check for failed requests or timeouts
  • Verify response data format

Future Enhancements

Planned Features

  • Alert Integration: Slack/email notifications for critical issues
  • Historical Charts: Trend analysis with time-series data
  • Mobile App: React Native companion application
  • Authentication: User management for production access
  • Export Features: PDF reports and CSV data export

Technical Improvements

  • TypeScript Migration: Enhanced type safety and developer experience
  • Testing Suite: Comprehensive unit and integration tests
  • PWA Features: Offline capability and push notifications
  • Real-time Updates: WebSocket integration for live data streaming

Support

For dashboard-related issues:

  1. Check this documentation or contact engineering for help
  2. Review browser console for error messages
  3. Test API endpoints independently
  4. Contact engineering team via Slack #engineering

Last updated: July 2025