giglez/docs/ERROR_LOGGING_GUIDE.md

Robust Error Logging System for Beta Testing

Overview

Comprehensive error tracking and monitoring system for GigLez file uploads during beta testing. Captures detailed context at every stage of the upload process to help diagnose and fix issues quickly.

---

Components

1. Server-Side Logging (src/logging/upload_logger.py)

Centralized logging system that tracks:

• Upload attempts with client info
• Individual file processing stages
• Parse errors with file samples
• GPS validation failures
• Device matching results
• Manual labels
• Performance metrics
• Exceptions with full context

Log Files Created:

logs/uploads/
├── uploads_2026-01-15.log              # All events (DEBUG level)
├── upload_errors_2026-01-15.log        # Errors only
├── uploads_structured_2026-01-15.jsonl # JSON for analysis
├── upload_performance_2026-01-15.log   # Performance metrics
└── problem_files/                      # Failed file samples
    └── upload_20260115_123456/
        └── problematic_file.sub.txt

2. Enhanced Upload Endpoint (src/api/routes/captures_with_logging.py)

New beta endpoint: POST /api/v1/captures/upload/beta

Logs every step of the upload process:

1. Validation - Manifest parsing, file count, total size
2. Parsing - .sub file parsing with detailed error context
3. GPS Validation - Coordinate validation
4. Storage - File storage timing
5. Matching - Device identification results
6. Database - Record creation
7. Complete - Final summary with performance metrics

3. Client-Side Error Reporter (static/js/error_reporter.js)

JavaScript error tracking that:

• Captures uncaught exceptions
• Reports parse errors with file samples
• Sends network errors
• Tracks browser/device info
• Queues errors if offline

Usage:

// Initialize (happens automatically)
window.errorReporter = new ErrorReporter();

// Set upload ID for tracking
errorReporter.setUploadId('upload_20260115_123456');

// Manually report errors
try {
    parseSubFile(content);
} catch (error) {
    errorReporter.reportParseError(filename, error, content);
}

4. Log Analysis Tool (scripts/analyze_upload_logs.py)

Command-line tool to analyze logs and generate reports.

---

Usage

During Beta Testing

1. Enable Beta Endpoint

Update upload form to use beta endpoint:

// In upload_enhanced.js
const response = await fetch('/api/v1/captures/upload/beta', {
    method: 'POST',
    body: formData
});

2. Include Error Reporter

Add to upload page HTML:

<!-- Error reporting -->
<script src="/static/js/error_reporter.js"></script>

<!-- Before upload -->
<script>
// Generate upload ID
const uploadId = errorReporter.generateUploadId();
errorReporter.setUploadId(uploadId);

// Include in manifest
manifest.upload_id = uploadId;
</script>

3. Monitor Logs in Real-Time

# Watch all uploads
tail -f logs/uploads/uploads_$(date +%Y-%m-%d).log

# Watch errors only
tail -f logs/uploads/upload_errors_$(date +%Y-%m-%d).log

# Watch structured JSON
tail -f logs/uploads/uploads_structured_$(date +%Y-%m-%d).jsonl | jq

Analyzing Logs

Daily Summary

python3 scripts/analyze_upload_logs.py --date 2026-01-15

Output:

================================================================================
Upload Log Analysis - 2026-01-15
================================================================================

📊 OVERVIEW
  Total Uploads:     152
  Total Files:       487
  Successful:        421 (91.2%)
  Failed:            41
  Duplicates:        25

👥 USERS
  Authenticated:     89
  Anonymous:         63

⚡ PERFORMANCE
  Parse Time:        45ms avg, 32ms median
  Matching Time:     128ms avg, 95ms median
  Total Time:        318ms avg, 256ms median

❌ TOP ERRORS
  SubFileParseError              23 occurrences
  GPSValidationError             12 occurrences
  NetworkError                    6 occurrences

🔍 PARSE ERRORS (23)
  capture_bad.sub                ValueError: Invalid frequency 0
  malformed.sub                  UnicodeDecodeError: invalid start byte

Last 7 Days Trend

python3 scripts/analyze_upload_logs.py --last 7

Specific Upload Investigation

python3 scripts/analyze_upload_logs.py --upload-id upload_20260115_123456

Output:

================================================================================
Upload Details: upload_20260115_123456
================================================================================

Total Events: 18

📅 TIMELINE:
  10:23:15.234 | upload_attempt       | 5 files, 2.3 MB
  10:23:15.456 | file_processing      | ✓ capture_001.sub - parsing (42ms)
  10:23:15.512 | file_processing      | ✓ capture_001.sub - matching (95ms)
  10:23:15.623 | matching_results     | 🔍 3 matches (95ms)
  10:23:15.701 | file_processing      | ✓ capture_001.sub - complete (267ms)
  10:23:15.889 | parse_error          | ❌ capture_002.sub - ValueError
  10:23:16.234 | upload_complete      | ✅ 4 success, 1 failed

---

Log Entry Types

1. Upload Attempt

{
  "event": "upload_attempt",
  "upload_id": "upload_20260115_123456",
  "timestamp": "2026-01-15T10:23:15.234Z",
  "user_id": 42,
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "file_count": 5,
  "total_size_bytes": 2415360,
  "total_size_mb": 2.3,
  "client_info": {
    "user_agent": "Mozilla/5.0 ...",
    "ip_address": "192.168.1.100",
    "referer": "https://giglez.com/upload"
  }
}

2. File Processing

{
  "event": "file_processing",
  "upload_id": "upload_20260115_123456",
  "timestamp": "2026-01-15T10:23:15.456Z",
  "filename": "capture_001.sub",
  "file_size": 512,
  "file_hash": "abc123...",
  "stage": "parsing",
  "success": true,
  "duration_ms": 42.15,
  "metadata": {
    "frequency": 433920000,
    "protocol": "Princeton",
    "modulation": "OOK"
  }
}

3. Parse Error

{
  "event": "parse_error",
  "upload_id": "upload_20260115_123456",
  "timestamp": "2026-01-15T10:23:15.889Z",
  "filename": "capture_002.sub",
  "file_hash": "def456...",
  "error_type": "ValueError",
  "error_message": "Invalid frequency: 0",
  "file_content_sample": "Filetype: Flipper SubGhz Key File\\nVersion: 1\\nFrequency: 0\\n...",
  "traceback": "Traceback (most recent call last):\\n  File ..."
}

Note: Full file sample saved to logs/uploads/problem_files/upload_20260115_123456/capture_002.sub.txt

4. GPS Validation Error

{
  "event": "gps_validation_error",
  "upload_id": "upload_20260115_123456",
  "timestamp": "2026-01-15T10:23:16.001Z",
  "filename": "capture_003.sub",
  "latitude": 999.0,
  "longitude": -200.5,
  "accuracy": 5.0,
  "reason": "Coordinates out of range or invalid"
}

5. Matching Results

{
  "event": "matching_results",
  "upload_id": "upload_20260115_123456",
  "timestamp": "2026-01-15T10:23:15.512Z",
  "filename": "capture_001.sub",
  "file_hash": "abc123...",
  "match_count": 3,
  "top_match": {
    "device_id": 123,
    "manufacturer": "Chamberlain",
    "model": "891LM",
    "confidence": 0.95
  },
  "all_matches": [...],
  "duration_ms": 95.23,
  "matcher_stats": {
    "strategies_used": 6,
    "total_candidates": 3
  }
}

6. Performance Metrics

{
  "event": "performance_metrics",
  "upload_id": "upload_20260115_123456",
  "timestamp": "2026-01-15T10:23:16.234Z",
  "avg_parse_time_ms": 45.2,
  "avg_matching_time_ms": 128.7,
  "avg_storage_time_ms": 12.3,
  "avg_db_time_ms": 23.1,
  "total_upload_time_ms": 1234.5
}

7. Client Error

{
  "event": "client_error",
  "upload_id": "upload_20260115_123456",
  "timestamp": "2026-01-15T10:23:16.500Z",
  "error_type": "SubFileParseError",
  "error_message": "Cannot read property 'frequency' of undefined",
  "client_info": {
    "user_agent": "Mozilla/5.0 ...",
    "platform": "Linux x86_64",
    "screen_width": 1920,
    "screen_height": 1080,
    "connection_type": "4g",
    "device_memory": 8
  },
  "stack_trace": "at parseSubFile (sub_parser.js:42:15)\\n..."
}

---

Common Issues & Solutions

Issue: High Parse Error Rate

Symptoms: 20%+ of files failing to parse

Diagnosis:

python3 scripts/analyze_upload_logs.py --date 2026-01-15 | grep "PARSE ERRORS" -A 10

Solutions:

1. Check logs/uploads/problem_files/ for actual file samples
2. Identify common error patterns
3. Update parser to handle edge cases
4. Add validation warnings in upload UI

Issue: Slow Matching Performance

Symptoms: Matching taking >500ms average

Diagnosis:

python3 scripts/analyze_upload_logs.py --date 2026-01-15 | grep "Matching Time"

Solutions:

1. Check database indexes on signatures table
2. Review matcher strategy order (put fast strategies first)
3. Consider caching frequent patterns
4. Profile matching code with cProfile

Issue: GPS Validation Failures

Symptoms: Users reporting valid coordinates being rejected

Diagnosis:

grep "gps_validation_error" logs/uploads/uploads_structured_2026-01-15.jsonl | jq

Solutions:

1. Review coordinate ranges in validator
2. Check for precision issues (too many decimal places)
3. Add client-side validation to catch before upload
4. Provide clear error messages

---

Monitoring Dashboard (Future)

Recommended metrics to track:

1. Upload Success Rate (daily)

   • Target: >95%
   • Alert if <90%

2. Average Processing Time (hourly)

   • Target: <500ms
   • Alert if >1000ms

3. Error Rate by Type (hourly)

   • Track top 5 error types
   • Alert on new error types

4. User Impact (daily)

   • % of users experiencing errors
   • % of files failing per user

5. Geographic Distribution (weekly)

   • Upload sources by country
   • Network quality by region

---

Retention Policy

Log Type	Retention	Reason
Main uploads log	90 days	Debugging window
Error log	180 days	Long-term analysis
Structured JSON	90 days	Analysis queries
Performance log	30 days	Recent trends only
Problem file samples	30 days	Storage constraints

Cleanup:

# Remove logs older than 90 days
find logs/uploads -name "uploads_*.log" -mtime +90 -delete

# Archive before deletion
tar -czf logs/archive/uploads_2026-01.tar.gz logs/uploads/uploads_2026-01-*.log

---

Privacy Considerations

What We Log:

• File metadata (frequency, protocol, size)
• GPS coordinates (as submitted)
• User ID (if authenticated)
• IP address
• Browser/device info

What We Don't Log:

• Full file contents (only first 500 chars on error)
• Passwords or tokens
• Personal identifying information beyond user ID

GDPR Compliance:

• Users can request deletion of their upload logs
• IP addresses can be anonymized (last octet masked)
• Option to disable client-side error reporting

---

Best Practices

For Developers:

1. Always use upload_id to correlate logs
2. Log before and after critical operations
3. Include context in exception logs (filename, user_id, etc.)
4. Use appropriate log levels:
   • DEBUG: Detailed diagnostic info
   • INFO: General events
   • WARNING: Potential issues
   • ERROR: Failures requiring attention
   • CRITICAL: System-wide failures

For Beta Testers:

1. Report upload IDs when filing bug reports
2. Include browser/device info (captured automatically)
3. Save screenshots of error messages
4. Note reproduction steps

For Operations:

1. Monitor error logs daily during beta
2. Set up alerts for error rate spikes
3. Review problem file samples weekly
4. Archive old logs monthly

---

API Reference

Server-Side Logging Functions

from src.logging.upload_logger import (
    log_upload_attempt,
    log_file_processing,
    log_parse_error,
    log_gps_validation_error,
    log_matching_results,
    log_manual_label,
    log_upload_complete,
    log_exception,
    log_performance_metrics,
    log_client_error,
    UploadStage
)

# Example: Log parse error
log_parse_error(
    upload_id="upload_20260115_123456",
    filename="capture.sub",
    file_content_sample=content[:500],
    error_type="ValueError",
    error_message=str(e),
    traceback_str=traceback.format_exc(),
    file_hash="abc123..."
)

Client-Side Error Reporter

// Global instance
window.errorReporter

// Set upload ID
errorReporter.setUploadId('upload_20260115_123456');

// Report errors
errorReporter.reportParseError(filename, error, fileContentSample);
errorReporter.reportUploadError(filename, error, stage);
errorReporter.reportValidationError(field, value, reason);
errorReporter.reportNetworkError(url, status, statusText);

// Flush error queue
await errorReporter.flushErrorQueue();

---

Troubleshooting

Logs not appearing?

Check:

1. Log directory exists: mkdir -p logs/uploads
2. Write permissions: chmod 755 logs/uploads
3. Loguru installed: pip install loguru
4. Logger initialized: Check src/logging/upload_logger.py import

Analysis script failing?

Common issues:

• Missing log files for date
• JSON parse errors in structured log
• Python version <3.7 (need 3.7+ for dataclasses)

Fix:

# Check log files exist
ls -la logs/uploads/

# Validate JSON
cat logs/uploads/uploads_structured_2026-01-15.jsonl | jq . > /dev/null

# Install dependencies
pip install loguru

---

Contact

Questions or Issues:

• GitHub: github.com/your-org/giglez/issues
• Email: support@giglez.com
• Slack: #giglez-beta-testing

---

Last Updated: 2026-01-16 Version: 1.0