Yaltopia-Ticket-Admin/dev-docs/ERROR_MONITORING.md

# Error Monitoring with Sentry

## Overview
This project uses **Sentry** for error tracking and performance monitoring.

## Setup

### 1. Create Sentry Account
1. Sign up at [sentry.io](https://sentry.io)
2. Create a new project
3. Select "React" as the platform
4. Copy your DSN

### 2. Configure Environment Variables

Add to `.env.production`:
```env
VITE_SENTRY_DSN=https://your-key@sentry.io/your-project-id
```

### 3. Sentry is Already Integrated

The following files have Sentry integration:
- `src/lib/sentry.ts` - Sentry initialization
- `src/main.tsx` - Sentry init on app start
- `src/components/ErrorBoundary.tsx` - Error boundary with Sentry

## Features

### 1. Error Tracking
All uncaught errors are automatically sent to Sentry:
```typescript
try {
  // Your code
} catch (error) {
  Sentry.captureException(error)
}
```

### 2. Performance Monitoring
Tracks page load times and API calls:
```typescript
tracesSampleRate: 0.1 // 10% of transactions
```

### 3. Session Replay
Records user sessions when errors occur:
```typescript
replaysOnErrorSampleRate: 1.0 // 100% on errors
replaysSessionSampleRate: 0.1 // 10% of normal sessions
```

### 4. Error Filtering
Filters out browser extension errors:
```typescript
beforeSend(event, hint) {
  // Filter logic
}
```

## Manual Error Logging

### Capture Exception
```typescript
import { Sentry } from '@/lib/sentry'

try {
  // risky operation
} catch (error) {
  Sentry.captureException(error, {
    tags: {
      section: 'user-management',
    },
    extra: {
      userId: user.id,
    },
  })
}
```

### Capture Message
```typescript
Sentry.captureMessage('Something important happened', 'info')
```

### Add Breadcrumbs
```typescript
Sentry.addBreadcrumb({
  category: 'auth',
  message: 'User logged in',
  level: 'info',
})
```

### Set User Context
```typescript
Sentry.setUser({
  id: user.id,
  email: user.email,
  username: user.name,
})
```

## Dashboard Features

### 1. Issues
View all errors with:
- Stack traces
- User context
- Breadcrumbs
- Session replays

### 2. Performance
Monitor:
- Page load times
- API response times
- Slow transactions

### 3. Releases
Track errors by release version:
```bash
# Set release in build
VITE_SENTRY_RELEASE=1.0.0 npm run build
```

### 4. Alerts
Configure alerts for:
- New issues
- Spike in errors
- Performance degradation

## Best Practices

### 1. Environment Configuration
```typescript
// Only enable in production
if (environment !== 'development') {
  Sentry.init({ ... })
}
```

### 2. Sample Rates
```typescript
// Production
tracesSampleRate: 0.1 // 10%
replaysSessionSampleRate: 0.1 // 10%

// Staging
tracesSampleRate: 1.0 // 100%
replaysSessionSampleRate: 0.5 // 50%
```

### 3. PII Protection
```typescript
replaysIntegration({
  maskAllText: true,
  blockAllMedia: true,
})
```

### 4. Error Grouping
Use fingerprinting for better grouping:
```typescript
beforeSend(event) {
  event.fingerprint = ['{{ default }}', event.message]
  return event
}
```

## Troubleshooting

### Errors Not Appearing
1. Check DSN is correct
2. Verify environment is not 'development'
3. Check browser console for Sentry errors
4. Verify network requests to Sentry

### Too Many Events
1. Reduce sample rates
2. Add more filters in beforeSend
3. Set up rate limiting in Sentry dashboard

### Missing Context
1. Add more breadcrumbs
2. Set user context after login
3. Add custom tags and extra data

## Cost Management

Sentry pricing is based on:
- Number of events
- Number of replays
- Data retention

Tips to reduce costs:
1. Lower sample rates in production
2. Filter out noisy errors
3. Use error grouping effectively
4. Set up spike protection

## Integration with CI/CD

### Upload Source Maps
```yaml
# In .github/workflows/deploy.yml
- name: Upload source maps to Sentry
  run: |
    npm install -g @sentry/cli
    sentry-cli releases new ${{ github.sha }}
    sentry-cli releases files ${{ github.sha }} upload-sourcemaps ./dist
    sentry-cli releases finalize ${{ github.sha }}    
  env:
    SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
    SENTRY_ORG: your-org
    SENTRY_PROJECT: your-project
```

## Resources

- [Sentry React Documentation](https://docs.sentry.io/platforms/javascript/guides/react/)
- [Sentry Performance Monitoring](https://docs.sentry.io/product/performance/)
- [Sentry Session Replay](https://docs.sentry.io/product/session-replay/)
- [Sentry Best Practices](https://docs.sentry.io/product/best-practices/)

## Support

For issues with Sentry integration:
1. Check Sentry documentation
2. Review browser console
3. Check Sentry dashboard
4. Contact Sentry support