talk2me/ADMIN_DASHBOARD.md

Talk2Me Admin Analytics Dashboard

A comprehensive analytics dashboard for monitoring and managing the Talk2Me application.

Features

Real-time Monitoring

• Request Volume: Track requests per minute, hour, and day
• Active Sessions: Monitor current active user sessions
• Error Rates: Real-time error tracking and analysis
• System Health: Monitor Redis, PostgreSQL, and ML services status

Analytics & Insights

• Translation & Transcription Metrics: Usage statistics by operation type
• Language Pair Analysis: Most popular translation combinations
• Response Time Monitoring: Track performance across all operations
• Cache Performance: Monitor cache hit rates for optimization

Performance Metrics

• Response Time Percentiles: P95 and P99 latency tracking
• Throughput Analysis: Requests per minute visualization
• Slow Request Detection: Identify and analyze performance bottlenecks
• Resource Usage: Memory and GPU utilization tracking

Data Management

• Export Capabilities: Download analytics data in JSON format
• Historical Data: View trends over time (daily, weekly, monthly)
• Error Logs: Detailed error tracking with stack traces
• Session Management: Track and manage user sessions

Setup

1. Database Setup

Initialize the analytics database tables:

python init_analytics_db.py

This creates the following tables:

• error_logs: Detailed error tracking
• request_logs: Request-level analytics
• translation_logs: Translation operation metrics
• transcription_logs: Transcription operation metrics
• tts_logs: Text-to-speech operation metrics
• daily_stats: Aggregated daily statistics

2. Configuration

Set the following environment variables:

# Admin access token (required)
export ADMIN_TOKEN="your-secure-admin-token"

# Database configuration
export DATABASE_URL="postgresql://user:password@localhost/talk2me"

# Redis configuration
export REDIS_URL="redis://localhost:6379/0"

3. Access the Dashboard

1. Navigate to: http://your-domain/admin
2. Enter your admin token
3. Access the analytics dashboard

Dashboard Sections

Overview Cards

• Total Requests (all-time and today)
• Active Sessions (real-time)
• Error Rate (24-hour percentage)
• Cache Hit Rate (performance metric)

Charts & Visualizations

Request Volume Chart

• Toggle between minute, hour, and day views
• Real-time updates every 5 seconds
• Historical data for trend analysis

Language Pairs Donut Chart

• Top 6 most used language combinations
• Visual breakdown of translation patterns

Operations Bar Chart

• Daily translation and transcription counts
• 7-day historical view

Response Time Line Chart

• Average, P95, and P99 response times
• Broken down by operation type

Error Analysis

• Error type distribution pie chart
• Recent errors list with details
• Timeline of error occurrences

Performance Table

• Detailed metrics for each operation type
• Average response times
• 95th and 99th percentile latencies

Real-time Updates

The dashboard uses Server-Sent Events (SSE) for real-time updates:

• Automatic refresh every 5 seconds
• Connection status indicator
• Automatic reconnection on disconnect

Data Export

Export analytics data for external analysis:

1. Click "Export Data" in the navigation
2. Choose data type:
   • requests: Request and operation counts
   • errors: Error logs and details
   • performance: Response time metrics
   • all: Complete data export

API Endpoints

The admin dashboard provides the following API endpoints:

Authentication Required

All endpoints require the X-Admin-Token header.

Available Endpoints

Overview Stats

GET /admin/api/stats/overview

Returns overall system statistics

Request Statistics

GET /admin/api/stats/requests/{timeframe}

Timeframes: minute, hour, day

Operation Statistics

GET /admin/api/stats/operations

Translation and transcription metrics

Error Statistics

GET /admin/api/stats/errors

Error types, timeline, and recent errors

Performance Statistics

GET /admin/api/stats/performance

Response times and throughput metrics

Data Export

GET /admin/api/export/{data_type}

Data types: requests, errors, performance, all

Real-time Updates

GET /admin/api/stream/updates

Server-Sent Events stream for real-time updates

Mobile Optimization

The dashboard is fully responsive and optimized for mobile devices:

• Touch-friendly controls
• Responsive charts that adapt to screen size
• Collapsible navigation for small screens
• Optimized data tables for mobile viewing

Security

• Admin token authentication required
• Session-based authentication after login
• Separate CORS configuration for admin endpoints
• All sensitive data masked in exports

Troubleshooting

Dashboard Not Loading

1. Check Redis and PostgreSQL connections
2. Verify admin token is set correctly
3. Check browser console for JavaScript errors

Missing Data

1. Ensure analytics middleware is initialized
2. Check database tables are created
3. Verify Redis is running and accessible

Real-time Updates Not Working

1. Check SSE support in your reverse proxy
2. Ensure X-Accel-Buffering: no header is set
3. Verify firewall allows SSE connections

Performance Considerations

• Charts limited to reasonable data points for performance
• Automatic data aggregation for historical views
• Efficient database queries with proper indexing
• Client-side caching for static data

Future Enhancements

• WebSocket support for lower latency updates
• Customizable dashboards and widgets
• Alert configuration for thresholds
• Integration with external monitoring tools
• Machine learning for anomaly detection