MyClub/DOCS/ANALYTICS_FIX.md

Analytics Admin Fix - 500 Error Resolution

Issue

The analytics admin page was throwing a 500 Internal Server Error when accessing:

GET http://localhost:8080/api/v1/admin/umami/pageviews?days=0

This caused the entire analytics dashboard to fail to load.

Root Cause

The Umami analytics endpoints (/pageviews, /stats, /metrics) were returning HTTP 500 errors when:

• Umami credentials were not configured
• Umami website ID was not set
• Umami API calls failed for any reason

Solution

Implemented graceful degradation for all Umami endpoints:

Changes Made

1. Added Configuration Checks (umami_controller.go)

   • All endpoints now check if Umami is configured before attempting API calls
   • Returns empty data structures instead of errors when Umami is unavailable

2. Improved Error Handling

   • GetPageviews: Returns [] (empty array) instead of 500 error
   • GetStats: Returns {} (empty object) instead of 500 error
   • GetMetrics: Returns [] (empty array) instead of 500 error

3. Enhanced Logging

   • Added detailed logging for debugging
   • Logs now include: websiteID, days parameter, unit, startAt/endAt timestamps
   • Clear warning messages when Umami is not configured

Benefits

✅ No More Crashes: Analytics page loads successfully even without Umami ✅ Better UX: Users see an empty dashboard instead of error page ✅ Clear Diagnostics: Log messages clearly indicate Umami configuration issues ✅ Resilient Design: Follows best practices for external service integration

Testing

After the fix, accessing the analytics admin page will:

• Load successfully ✓
• Show empty charts and stats when Umami is not configured
• Display data normally when Umami is properly configured

Configuration

To enable Umami analytics, ensure these environment variables are set in .env:

UMAMI_URL=https://your-umami-instance.com
UMAMI_USERNAME=your_username
UMAMI_PASSWORD=your_password
UMAMI_WEBSITE_ID=  # Optional - will auto-detect

Files Modified

• internal/controllers/umami_controller.go
  • GetStats() - Lines 196-236
  • GetMetrics() - Lines 238-284
  • GetPageviews() - Lines 286-349

Deployment

# Rebuild and restart the backend container
docker-compose up -d --build backend

# Or if running locally
go build -o bin/fotbal-club main.go
./bin/fotbal-club

Related Documentation

• See ANALYTICS_INTEGRATION.md for full Umami setup guide
• See QUICK_START_ANALYTICS.md for analytics dashboard usage