mirror of
https://github.com/Dvorinka/MyClubServer.git
synced 2026-06-04 18:52:56 +00:00
upload
This commit is contained in:
Tomáš Dvořák
@@ -0,0 +1,199 @@
|
||||
# Analytics Graph Improvements - Summary
|
||||
|
||||
## Problem Identified
|
||||
The analytics graph displayed no data visually, showing an empty chart with no bars or information.
|
||||
|
||||
## Root Cause
|
||||
- **UMAMI_WEBSITE_ID** is empty in the `.env` file
|
||||
- Backend was returning empty data arrays `{}` and `[]` when Umami connection failed
|
||||
- No visual feedback to indicate why analytics were not working
|
||||
- Limited logging made troubleshooting difficult
|
||||
|
||||
## Solutions Implemented
|
||||
|
||||
### 1. Enhanced Frontend Error Handling
|
||||
**File**: `frontend/src/pages/admin/AnalyticsAdminPage.tsx`
|
||||
|
||||
#### Changes:
|
||||
- **Added state variables**:
|
||||
- `hasData`: Tracks whether any analytics data was received
|
||||
- `errorMessage`: Stores user-friendly error messages
|
||||
|
||||
- **Data validation**:
|
||||
- Checks if stats contain actual values (pageviews > 0, visitors > 0)
|
||||
- Validates pageviews array has non-zero values
|
||||
- Verifies metrics arrays have data
|
||||
|
||||
- **Visual improvements**:
|
||||
- **Orange warning card** when no data is available with:
|
||||
- Clear error message in Czech
|
||||
- List of possible causes
|
||||
- Step-by-step troubleshooting instructions
|
||||
- "Reload page" button for retry
|
||||
- **Empty state** in graph area when no pageviews exist
|
||||
- Friendly icon and message: "Žádná data pro zobrazení"
|
||||
|
||||
### 2. Enhanced Backend Logging
|
||||
**Files**:
|
||||
- `internal/controllers/umami_controller.go`
|
||||
- `internal/services/umami_service.go`
|
||||
|
||||
#### Changes:
|
||||
- **Detailed logging at every step**:
|
||||
```go
|
||||
// Before: No logging
|
||||
// After:
|
||||
logger.Info("UMAMI_WEBSITE_ID is empty, attempting to auto-detect...")
|
||||
logger.Info("Attempting to find Umami website by domain: %s", host)
|
||||
logger.Info("Found default Umami website: ID=%s, Name=%s, Domain=%s", ...)
|
||||
logger.Info("Successfully fetched Umami stats for websiteID=%s (days=%d)", ...)
|
||||
```
|
||||
|
||||
- **Better error messages**:
|
||||
- Shows which configuration values are missing
|
||||
- Displays URLs being attempted
|
||||
- Logs authentication success/failure with timestamps
|
||||
- Shows website detection process step-by-step
|
||||
|
||||
- **Improved resolveWebsiteID**:
|
||||
- Logs when using cached ID
|
||||
- Logs when attempting auto-detection
|
||||
- Logs domain matching attempts
|
||||
- Logs fallback to first available website
|
||||
|
||||
### 3. Graceful Fallback Behavior
|
||||
- API endpoints return empty objects/arrays instead of errors
|
||||
- Frontend handles empty data without crashing
|
||||
- Clear user feedback instead of silent failures
|
||||
|
||||
## User Experience Improvements
|
||||
|
||||
### Before:
|
||||
- Empty graph with no explanation
|
||||
- No indication of what's wrong
|
||||
- Difficult to diagnose issues
|
||||
- Required checking backend logs
|
||||
|
||||
### After:
|
||||
- **If configured correctly**:
|
||||
- Statistics display normally
|
||||
- Graph shows pageview data
|
||||
- All metrics visible
|
||||
|
||||
- **If not configured**:
|
||||
- Orange warning banner explains the issue
|
||||
- Lists possible causes
|
||||
- Provides clear troubleshooting steps
|
||||
- Reload button for easy retry
|
||||
|
||||
- **If no traffic yet**:
|
||||
- Empty state with friendly message
|
||||
- Clear indication this is expected
|
||||
- No alarming error messages
|
||||
|
||||
## Technical Details
|
||||
|
||||
### Auto-Detection Flow:
|
||||
1. Check if `UMAMI_WEBSITE_ID` is set → Use it
|
||||
2. Try to match by `FRONTEND_BASE_URL` domain
|
||||
3. Fall back to first available website in Umami
|
||||
4. Cache the detected ID in memory
|
||||
5. Log each step for transparency
|
||||
|
||||
### Error Detection Logic:
|
||||
```typescript
|
||||
const hasAnyStats = statsResponse.data && (
|
||||
(statsResponse.data.pageviews?.value && statsResponse.data.pageviews.value > 0) ||
|
||||
(statsResponse.data.visitors?.value && statsResponse.data.visitors.value > 0)
|
||||
);
|
||||
|
||||
const hasPageviews = pageviewsDataArray.length > 0 &&
|
||||
pageviewsDataArray.some(d => d.value > 0);
|
||||
|
||||
const hasMetrics = pages.data?.length > 0 || countries.data?.length > 0;
|
||||
|
||||
setHasData(hasAnyStats || hasPageviews || hasMetrics);
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### To verify the fix works:
|
||||
1. Restart backend server
|
||||
2. Open `/admin/analytika`
|
||||
3. Check for:
|
||||
- Orange warning if not configured (expected)
|
||||
- Graph with data if configured
|
||||
- Clear error messages instead of blank page
|
||||
|
||||
### To generate test data:
|
||||
1. Visit your website multiple times
|
||||
2. Navigate between pages
|
||||
3. Wait 2-5 minutes
|
||||
4. Refresh analytics page
|
||||
5. Data should appear
|
||||
|
||||
## Files Modified
|
||||
|
||||
1. **frontend/src/pages/admin/AnalyticsAdminPage.tsx**
|
||||
- Added error state management
|
||||
- Enhanced visual feedback
|
||||
- Better empty states
|
||||
|
||||
2. **internal/controllers/umami_controller.go**
|
||||
- Enhanced logging throughout
|
||||
- Better error messages
|
||||
- Improved website ID resolution
|
||||
|
||||
3. **internal/services/umami_service.go**
|
||||
- Added logging to authentication
|
||||
- Better website detection logs
|
||||
- Improved error messages
|
||||
|
||||
4. **Documentation** (new):
|
||||
- `ANALYTICS_GRAPH_FIX.md` - Detailed troubleshooting guide
|
||||
- `ANALYTICS_TEST_INSTRUCTIONS.md` - Step-by-step testing guide
|
||||
- `ANALYTICS_IMPROVEMENTS_SUMMARY.md` - This file
|
||||
|
||||
## Configuration Reference
|
||||
|
||||
Required in `.env`:
|
||||
```env
|
||||
UMAMI_URL=https://umami.tdvorak.dev # ✓ Set
|
||||
UMAMI_USERNAME=admin # ✓ Set
|
||||
UMAMI_PASSWORD=eevRQ6h3G@!c#y4A1T # ✓ Set
|
||||
UMAMI_WEBSITE_ID= # Empty (will auto-detect)
|
||||
```
|
||||
|
||||
## Benefits
|
||||
|
||||
1. **Better User Experience**: Clear feedback instead of confusion
|
||||
2. **Easier Troubleshooting**: Logs show exactly what's happening
|
||||
3. **Self-Healing**: Auto-detects website ID when possible
|
||||
4. **Production Ready**: Graceful handling of all failure scenarios
|
||||
5. **Maintainable**: Clear code with good error messages
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Restart backend** to apply changes
|
||||
2. **Test the analytics page** to verify it works
|
||||
3. **Monitor logs** for any connection issues
|
||||
4. **Create Umami website** if none exists
|
||||
5. **Optional**: Set `UMAMI_WEBSITE_ID` in `.env` once detected
|
||||
|
||||
## Monitoring
|
||||
|
||||
Watch these log messages:
|
||||
- `✓ Successfully authenticated with Umami`
|
||||
- `✓ Found default Umami website: ID=...`
|
||||
- `✓ Successfully fetched Umami stats`
|
||||
- `✗ No Umami websites found` → Create website
|
||||
- `✗ Authentication failed` → Check credentials
|
||||
- `✗ Failed to resolve Umami website ID` → Check connection
|
||||
|
||||
## Support
|
||||
|
||||
If issues persist:
|
||||
1. Check backend logs for errors
|
||||
2. Verify Umami is accessible at configured URL
|
||||
3. Ensure website exists in Umami dashboard
|
||||
4. Review documentation in `ANALYTICS_GRAPH_FIX.md`
|
||||
Reference in New Issue
Block a user