Skip to main content

Source: ocean/docs/sentry-configuration-guide.md | ✏️ Edit on GitHub

Comprehensive Sentry Configuration Guide

This guide documents our complete Sentry setup, including all configurations, best practices, and monitoring strategies.

Table of Contents​

  1. Overview
  2. Frontend Configuration
  3. Edge Functions Configuration
  4. Database Monitoring
  5. Alert Rules
  6. Security & Privacy
  7. Performance Optimization
  8. Troubleshooting

Overview​

Our Sentry implementation provides comprehensive observability across:

  • Frontend React application
  • Supabase Edge Functions
  • Database operations
  • User journeys and interactions

Key Features​

  • Cost-optimized for Sentry Team plan limits
  • Privacy-first with no PII collection by default
  • Performance monitoring with INP and Core Web Vitals
  • Distributed tracing across frontend and backend
  • Custom instrumentation for business metrics

Frontend Configuration​

Initialization​

The Sentry SDK is initialized in src/lib/sentry.tsx with:

// Production sampling rates (cost-optimized)
tracesSampleRate: 0.2 // 20% of transactions
replaysSessionSampleRate: 0.05 // 5% of sessions
replaysOnErrorSampleRate: 1.0 // 100% on errors
profilesSampleRate: 0.05 // 5% of transactions

Error Filtering​

We filter out common noise:

  • Browser extension errors
  • ResizeObserver warnings
  • Network timeouts from third-party scripts
  • Non-critical console messages

Custom Integrations​

  1. Browser Tracing - Monitors API calls, navigation, and user interactions
  2. Session Replay - Records user sessions with privacy masking
  3. Profiling - Identifies performance bottlenecks

Edge Functions Configuration​

Each Edge Function includes Sentry monitoring via _shared/observability.ts:

Features​

  • Distributed tracing with frontend correlation
  • Structured logging with JSON output
  • Custom metrics collection (Prometheus-style)
  • Error context with request details

Usage Example​

import { Logger } from '../_shared/observability.ts'
import { withTracing } from '../_shared/sentry-tracing.ts'

const logger = new Logger({ functionName: 'my-function' })

serve(
  withTracing('my-function', async (req) => {
    logger.info('Processing request', { method: req.method })
    // Function logic
  })
)

Database Monitoring​

Query Performance Tracking​

The sentry-database-monitoring.ts module wraps Supabase client to track:

  • Query execution times
  • Slow queries (>1 second)
  • Failed queries with error context
  • Auth operations

Database Schema Monitoring​

The monitoring schema tracks:

  • Slow query patterns
  • Trigger execution performance
  • Webhook delivery attempts

Automated Alerts​

The MonitoringAlertSystem checks every 5 minutes for:

  • Queries averaging >5 seconds
  • Database trigger failures
  • Webhook success rates <95%

Alert Rules​

Configure these rules in your Sentry dashboard:

Critical Alerts (Immediate Action)​

  1. Payment Failures - Any Stripe/billing errors
  2. Security Violations - Auth failures, suspicious activity
  3. Data Integrity - Database constraint violations
  4. API Downtime - 500/503 errors exceeding threshold

Warning Alerts (Investigation Required)​

  1. High Error Rate - >50 errors in 5 minutes
  2. Slow Transactions - p95 >3 seconds
  3. Memory Leaks - Heap usage >90%
  4. Low Crash-Free Rate - <95% sessions

Informational Alerts​

  1. User Experience - INP >500ms
  2. Rate Limiting - Frequent rate limit hits
  3. Third-Party Failures - External API issues

Security & Privacy​

Data Sanitization​

  • No PII collected by default (sendDefaultPii: false)
  • Sensitive headers redacted in Edge Functions
  • Password fields masked in replays
  • API keys filtered from error context

Production Protection​

  • Sentry removed from window object in production
  • Console methods overridden to prevent logging
  • Source maps uploaded but not exposed publicly

Compliance​

  • GDPR compliant with user consent for email collection
  • Data retention policies aligned with privacy requirements
  • User deletion propagated to Sentry

Performance Optimization​

Sampling Strategy​

// Dynamic sampling based on importance
if (isPaymentFlow) {
  Sentry.getCurrentHub().getScope()?.setTransactionSampleRate(1.0)
}

Rate Limiting​

Custom rate limiter prevents flooding:

rateLimitedCaptureException(error) // Max 10 per minute per error type

Memory Monitoring​

Automatic heap size monitoring with alerts:

startMemoryMonitoring() // Checks every 30 seconds

Troubleshooting​

Common Issues​

  1. Missing Source Maps

    • Verify SENTRY_AUTH_TOKEN in CI/CD
    • Check Vite build configuration
    • Ensure release version matches

  2. No Errors Appearing

    • Verify DSN configuration
    • Check browser console for initialization errors
    • Ensure not filtered by beforeSend

  3. High Quota Usage

    • Review sampling rates
    • Check for error loops
    • Enable rate limiting

Debug Mode​

In development:

window.Sentry.captureException(new Error('Test'))
window.Sentry.showReportDialog()

Verification​

Test your setup:

  1. Navigate to /admin/sentry-debug
  2. Click "Test Error Handling"
  3. Verify error appears in Sentry dashboard

Maintenance​

Regular Tasks​

  1. Weekly

    • Review error trends
    • Check quota usage
    • Update ignore patterns

  2. Monthly

    • Analyze performance metrics
    • Review alert thresholds
    • Clean up resolved issues

  3. Quarterly

    • Update SDK version
    • Review sampling rates
    • Audit security settings

Resources​