Skip to main content

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

Frontend Sentry Integration Guide

1. Overview​

The frontend Sentry integration provides cost-optimized error tracking, performance monitoring, and session replay for the Ocean application. This guide has been updated to reflect the latest changes and recommendations from the recent Sentry audit.

2. Key Features​

2.1. Smart Sampling​

  • Transactions: 10% in production (captures performance data)
  • Errors: 100% always captured
  • Session Replays: 1% normally, 100% on error
  • Cost Impact: ~90% reduction in Sentry events

2.2. Privacy Protection​

  • All text masked in session replays
  • No cookies or auth headers sent
  • User data limited to ID only
  • Network requests excluded from replays

2.3. Noise Filtering​

Automatically ignores:

  • Browser extension errors
  • Network timeouts
  • ResizeObserver warnings
  • Third-party script errors

3. Implementation Details​

3.1. Initialization (src/lib/sentry.ts)​

// Main app entry (src/main.tsx)
import { initSentry } from './lib/sentry'
initSentry() // Before anything else

3.2. User Context​

Automatically set when auth state changes:

// src/contexts/auth-context.tsx
setSentryUser({
  id: user.id,
  email: user.email, // Only in dev
  plan: user.plan, // For segmentation
})

3.3. Error Boundaries​

Two levels of protection:

  1. SentryErrorBoundary: Captures and reports errors
  2. Custom ErrorBoundary: Fallback UI

3.4. Performance Monitoring​

Critical operations are profiled (10% sample):

profileOperation('checkout.complete', async () => {
  // Critical user flow
})

4. What Gets Tracked​

4.1. Automatically Captured​

  • ✅ JavaScript errors
  • ✅ Unhandled promise rejections
  • ✅ GraphQL errors (critical only)
  • ✅ Auth failures
  • ✅ Performance metrics (sampled)

4.2. NOT Captured (Cost Savings)​

  • ❌ Debug/info logs
  • ❌ Network errors (usually not actionable)
  • ❌ Browser extension conflicts
  • ❌ Non-error events

5. Usage Patterns​

5.1. Component Error Handling​

import { useErrorHandler } from '@/lib/sentry'

function MyComponent() {
  const handleError = useErrorHandler()

  try {
    // risky operation
  } catch (error) {
    handleError(error)
  }
}

5.2. Custom Event Tracking​

import { trackEvent } from '@/lib/sentry'

// Sampled at 10% in production
trackEvent('tenant.provisioned', {
  region: 'us-east-1',
  plan: 'pro',
})

5.3. GraphQL Error Context​

Errors automatically include:

  • Query/mutation name
  • Variables (sanitized)
  • GraphQL error codes
  • User context

6. Cost Optimization​

6.1. Current Settings​

  • Transactions: 10% sample rate
  • Replays: 1% sample rate (100% on error)
  • Profiles: 1% of transactions
  • Estimated Cost: $0-50/month for most apps

6.2. When You'll Hit Limits​

  • Free tier: 5K errors/month
  • If exceeded: Increase filtering, reduce sampling

6.3. Adjustment Levers​

// Reduce costs further if needed
tracesSampleRate: 0.05,        // 5% instead of 10%
replaysSessionSampleRate: 0,   // Disable replays
profilesSampleRate: 0,         // Disable profiling

7. Debugging with Sentry​

7.1. Error Investigation​

  1. Check Sentry dashboard for error
  2. View session replay (if captured)
  3. Check breadcrumbs for user actions
  4. Review error context and tags

7.2. Performance Issues​

  1. Go to Performance tab
  2. Filter by transaction name
  3. Check P95 latencies
  4. Drill into slow traces

7.3. User Journey​

  1. Find user by ID
  2. View their session timeline
  3. See errors in context
  4. Watch replay if available

8. Best Practices​

8.1. DO ✅​

  • Add context to errors when catching
  • Use meaningful transaction names
  • Profile critical user paths
  • Set user context on auth

8.2. DON'T ❌​

  • Log sensitive data
  • Create high-cardinality tags
  • Track every button click
  • Use Sentry for analytics

9. Integration with Backend​

9.1. Trace Propagation​

Frontend → Backend traces are connected:

// Automatically added to GraphQL requests
headers: {
  'sentry-trace': getCurrentTrace(),
  'baggage': getBaggage()
}

9.2. Unified Error View​

  • Frontend errors show user context
  • Backend errors show request origin
  • Full trace from UI to database

10. Emergency Procedures​

10.1. If Sentry Causes Issues​

  1. Disable in production:

    // src/lib/sentry.ts
    dsn: undefined // Disables Sentry

  2. Reduce sampling:

    tracesSampleRate: 0.01 // 1%

  3. Filter more aggressively:

    beforeSend(event) {
      // Only send critical errors
      if (event.level !== 'error') return null
      if (!event.exception) return null
      return event
    }

11. Monitoring Sentry Usage​

Check monthly usage:

  1. Sentry Dashboard → Settings → Usage
  2. Monitor: Errors, Transactions, Replays
  3. Set up billing alerts

12. Future Enhancements & Audit Recommendations​

12.1. Source Map Uploads​

Status: Not Implemented

Recommendation: Configure your build process to automatically upload source maps to Sentry. This will de-minify error stack traces and make them easier to debug.

  • Use the @sentry/vite-plugin to automatically upload source maps during the build process.
  • Update your vite.config.ts to include the Sentry plugin.

12.2. User Feedback Integration​

Status: Not Implemented

Recommendation: Implement a user feedback form that is displayed when an error occurs. This will allow you to collect valuable context from users and help you debug issues more effectively.

  • Use the Sentry.showReportDialog method to open the feedback dialog.

12.3. Custom Instrumentation​

Status: Partially Implemented

Recommendation: Enhance performance monitoring by adding custom spans to track the performance of critical operations in your application.

  • Use the Sentry.startTransaction and span.finish methods to create custom transactions and spans.
  • Review your transaction names to ensure they are descriptive and consistent.

12.4. Alerting and Triage​

Status: Not Implemented

Recommendation: Configure alerting rules in Sentry to notify you of new and high-priority issues. Use the triage features in Sentry to assign issues to team members and track their progress.