feat(backend): Add Sentry error tracking integration (#54)

FEATURES:
- Sentry SDK integration with FastAPI
- Automatic error capture with full stack traces
- User context attached to errors (user_id, email)
- Performance monitoring (10% sample in production)
- Smart filtering (ignores health checks, bot paths)

IMPLEMENTATION:
- services/sentry.py: init_sentry(), set_user_context(), capture_exception()
- main.py: Initialize Sentry before other imports
- middleware/auth.py: Set user context after authentication

CONFIGURATION:
- SENTRY_DSN: Your Sentry project DSN
- ENVIRONMENT: development/staging/production

Sentry is optional - app works fine without SENTRY_DSN set.

Closes #54

Author: DevanshuNEU

.env.example

@@ -34,3 +34,8 @@ ALLOWED_ORIGINS=http://localhost:3000
 # Redis (auto-configured in Docker, set REDIS_URL in Railway)
 REDIS_HOST=redis
 REDIS_PORT=6379
+
+# Sentry Error Tracking (Optional but recommended for production)
+# Get DSN from: https://sentry.io → Settings → Projects → Client Keys
+SENTRY_DSN=
+ENVIRONMENT=development  # development, staging, production

backend/.env.example

@@ -18,3 +18,8 @@ ALLOWED_ORIGINS=http://localhost:3000
 # Redis Cache
 REDIS_HOST=localhost
 REDIS_PORT=6379
+
+# Sentry Error Tracking (Optional)
+# Get DSN from https://sentry.io → Settings → Projects → Client Keys
+SENTRY_DSN=
+ENVIRONMENT=development

backend/main.py

@@ -10,6 +10,10 @@
 from starlette.responses import JSONResponse
 import os
 
+# Initialize Sentry FIRST (before other imports to catch all errors)
+from services.sentry import init_sentry
+init_sentry()
+
 # Import API config (single source of truth for versioning)
 from config.api import API_PREFIX, API_VERSION
 

backend/middleware/auth.py

@@ -122,11 +122,17 @@ def _authenticate(token: str) -> AuthContext:
     # Try JWT (Supabase tokens)
     ctx = _validate_jwt(token)
     if ctx:
+        # Set Sentry user context for error tracking
+        from services.sentry import set_user_context
+        set_user_context(user_id=ctx.user_id, email=ctx.email)
         return ctx
 
     # Try API key
     ctx = _validate_api_key(token)
     if ctx:
+        # Set Sentry user context for error tracking
+        from services.sentry import set_user_context
+        set_user_context(user_id=ctx.user_id or ctx.api_key_name)
         return ctx
 
     # Neither worked

backend/requirements.txt

@@ -36,3 +36,6 @@ pyjwt>=2.8.0  # JWT token verification for Supabase Auth
 pytest>=8.0.0
 pytest-asyncio>=0.24.0
 pytest-cov>=6.0.0
+
+# Observability
+sentry-sdk[fastapi]>=2.0.0

backend/services/sentry.py

@@ -0,0 +1,137 @@
+"""
+Sentry Error Tracking Integration
+Provides production error visibility and performance monitoring
+"""
+import os
+from typing import Optional
+
+
+def init_sentry() -> bool:
+    """
+    Initialize Sentry SDK if SENTRY_DSN is configured.
+    
+    Returns:
+        bool: True if Sentry was initialized, False otherwise
+    """
+    sentry_dsn = os.getenv("SENTRY_DSN")
+    
+    if not sentry_dsn:
+        print("ℹ️  Sentry DSN not configured - error tracking disabled")
+        return False
+    
+    try:
+        import sentry_sdk
+        from sentry_sdk.integrations.fastapi import FastApiIntegration
+        from sentry_sdk.integrations.starlette import StarletteIntegration
+        
+        environment = os.getenv("ENVIRONMENT", "development")
+        
+        sentry_sdk.init(
+            dsn=sentry_dsn,
+            environment=environment,
+            
+            # Performance monitoring - sample 10% of transactions in production
+            traces_sample_rate=0.1 if environment == "production" else 1.0,
+            
+            # Profile 10% of sampled transactions
+            profiles_sample_rate=0.1,
+            
+            # Send PII like user IDs (we need this for debugging)
+            send_default_pii=True,
+            
+            # Integrations
+            integrations=[
+                FastApiIntegration(transaction_style="endpoint"),
+                StarletteIntegration(transaction_style="endpoint"),
+            ],
+            
+            # Filter out health check noise
+            before_send=_filter_events,
+            
+            # Don't send in debug mode
+            debug=environment == "development",
+        )
+        
+        print(f"✅ Sentry initialized (environment: {environment})")
+        return True
+        
+    except ImportError:
+        print("⚠️  sentry-sdk not installed - error tracking disabled")
+        return False
+    except Exception as e:
+        print(f"⚠️  Failed to initialize Sentry: {e}")
+        return False
+
+
+def _filter_events(event, hint):
+    """
+    Filter out noisy events before sending to Sentry.
+    """
+    # Don't send health check errors
+    if "health" in event.get("request", {}).get("url", ""):
+        return None
+    
+    # Don't send 404s for common bot paths
+    if event.get("exception"):
+        exception_value = str(event["exception"].get("values", [{}])[0].get("value", ""))
+        bot_paths = ["/wp-admin", "/wp-login", "/.env", "/config", "/admin"]
+        if any(path in exception_value for path in bot_paths):
+            return None
+    
+    return event
+
+
+def set_user_context(user_id: Optional[str] = None, email: Optional[str] = None):
+    """
+    Set user context for error tracking.
+    Call this after authentication to attach user info to errors.
+    
+    Args:
+        user_id: The authenticated user's ID
+        email: The user's email (optional)
+    """
+    try:
+        import sentry_sdk
+        sentry_sdk.set_user({
+            "id": user_id,
+            "email": email,
+        })
+    except ImportError:
+        pass  # Sentry not installed
+
+
+def capture_exception(error: Exception, **extra_context):
+    """
+    Manually capture an exception with additional context.
+    
+    Args:
+        error: The exception to capture
+        **extra_context: Additional context to attach
+    """
+    try:
+        import sentry_sdk
+        with sentry_sdk.push_scope() as scope:
+            for key, value in extra_context.items():
+                scope.set_extra(key, value)
+            sentry_sdk.capture_exception(error)
+    except ImportError:
+        pass  # Sentry not installed
+
+
+def capture_message(message: str, level: str = "info", **extra_context):
+    """
+    Capture a message (not an exception) for tracking.
+    
+    Args:
+        message: The message to capture
+        level: Severity level (info, warning, error)
+        **extra_context: Additional context to attach
+    """
+    try:
+        import sentry_sdk
+        with sentry_sdk.push_scope() as scope:
+            for key, value in extra_context.items():
+                scope.set_extra(key, value)
+            sentry_sdk.capture_message(message, level=level)
+    except ImportError:
+        pass  # Sentry not installed