Skip to main content

Source: ocean/docs/adr/0039-sentry-v9-monitoring-implementation.md | ✏️ Edit on GitHub

ADR-003: Sentry v9 Advanced Monitoring Implementation

Date: 2025-07-30
Status: Accepted
Deciders: Engineering Team
Tags: monitoring, observability, error-tracking, performance

Context​

We needed a comprehensive monitoring solution to track errors, performance, and user journeys in our production application. Our requirements included:

  1. Real-time error tracking with actionable insights
  2. Performance monitoring for critical user flows
  3. Cost-effective solution within free tier limits
  4. Privacy-compliant implementation (no PII leakage)
  5. Future-proof architecture using latest SDK versions

Initial investigation revealed our Sentry integration wasn't working due to a misconfigured DSN (trailing newline character) and we were not utilizing Sentry's full capabilities.

Decision​

We decided to implement Sentry v9 with advanced monitoring features, specifically:

  1. Upgrade to Sentry v9 SDK (@sentry/React ^9.43.0) for latest features and API compatibility
  2. Implement User Flow Tracking using custom performance monitoring
  3. Add Cron Monitoring adapted for browser environment
  4. Optimize Sampling Rates for free tier (10K errors, 100K transactions/month)
  5. Create Comprehensive Error Filtering to reduce noise
  6. Track GraphQL and Stripe Operations for API performance insights

Consequences​

Positive​

  1. Complete Observability: Full visibility into user journeys, not just isolated errors
  2. Cost Efficiency: Optimized sampling keeps us within free tier limits
  3. Actionable Insights: Smart filtering reduces noise, surfaces real issues
  4. Performance Monitoring: Identifies bottlenecks in critical flows
  5. Future-Proof: Using v9 APIs ensures compatibility with future updates
  6. Developer Experience: Easy-to-use hooks and utilities for adding monitoring

Negative​

  1. Sampling Trade-offs: 10% trace sampling means we miss 90% of transactions
  2. Browser Limitations: Some features (like native cron monitoring) aren't available in browser SDK
  3. Bundle Size: Sentry SDK adds ~50KB to bundle (mitigated by code splitting)
  4. Learning Curve: Team needs to understand new v9 APIs and monitoring patterns

Neutral​

  1. Maintenance Overhead: Requires periodic review of sampling rates and alert rules
  2. Privacy Considerations: Must carefully manage what data is sent to Sentry

Implementation Details​

1. Core Configuration (/src/lib/sentry.tsx)​

Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN?.trim(), // Fix: trim whitespace
  tracesSampleRate: 0.1, // 10% in production
  replaysSessionSampleRate: 0.01, // 1% in production
  replaysOnErrorSampleRate: 1.0, // Always on error
  sendDefaultPii: false, // Privacy first
})

2. User Flow Tracking (/src/lib/sentry-performance.ts)​

// Track complete user journeys
const flow = new UserFlowTracker()
flow.startFlow('authentication')
flow.trackStep('enter-email', { email_domain })
flow.trackStep('verify-otp')
flow.completeFlow()

3. GraphQL Integration​

// Automatic performance tracking for all queries
Sentry.startSpan({
  name: `graphql.${operationName}`,
  op: 'graphql.query',
  attributes: { variables },
})

4. Error Filtering​

// Ignore non-actionable errors
ignoreErrors: [
  'ResizeObserver loop limit exceeded',
  'chrome-extension://',
  'NetworkError',
  'Script error',
]

Alternatives Considered​

  1. LogRocket: More expensive, includes session replay by default
  2. Datadog: Enterprise-focused, overkill for our needs
  3. Custom Solution: Too much maintenance overhead
  4. PostHog Only: Lacks robust error tracking capabilities
  5. Sentry v8: Would require migration later, missing new features

Migration Path​

  1. ✅ Fix DSN configuration issue
  2. ✅ Upgrade to Sentry v9
  3. ✅ Implement user flow tracking
  4. ✅ Add GraphQL/Stripe monitoring
  5. ✅ Configure alerts and ownership
  6. 🔄 Monitor usage and adjust sampling rates (ongoing)

Lessons Learned​

  1. Environment Variables: Always validate and trim environment variables
  2. SDK Versions: Stay current with major versions for better APIs
  3. Sampling Strategy: Start conservative, increase based on actual usage
  4. User Journeys: Flow tracking provides more value than isolated error tracking
  5. Documentation: Comprehensive setup guides essential for team adoption

References​