# Sentry Error Tracking

Yemaya uses Sentry for error tracking, performance monitoring, and release
management.

## Overview

The Sentry integration provides:

- **Error Tracking**: Capture and aggregate errors across all services
- **Performance Monitoring**: Track transaction performance and bottlenecks
- **Release Tracking**: Associate errors with specific releases
- **Source Maps**: See original source code in stack traces
- **Alerting**: Get notified of issues via Slack, email, PagerDuty

## Quick Start

### Using Self-Hosted Sentry

```bash
# Complete setup (first time)
./scripts/sentry-setup.sh full

# Or step-by-step:
./scripts/sentry-setup.sh infra    # Start databases
./scripts/sentry-setup.sh init     # Initialize DB
./scripts/sentry-setup.sh snuba    # Start query engine
./scripts/sentry-setup.sh sentry   # Start Sentry
./scripts/sentry-setup.sh admin    # Create admin user
```

### Access Sentry

| Service      | URL                   | Description     |
| ------------ | --------------------- | --------------- |
| Sentry UI    | http://localhost:9000 | Main dashboard  |
| Sentry Relay | http://localhost:3001 | Event ingestion |

### Using Sentry Cloud

If using Sentry.io (cloud):

1. Create organization at https://sentry.io
2. Create projects for each service
3. Copy DSNs to environment variables

## Configuration

### Environment Variables

```bash
# Sentry DSN (Data Source Name)
SENTRY_DSN=https://<key>@localhost:9000/<project-id>

# Or for Sentry Cloud
SENTRY_DSN=https://<key>@sentry.io/<project-id>

# Environment name
SENTRY_ENVIRONMENT=development  # production, staging

# Release version
SENTRY_RELEASE=yemaya@1.0.0

# Sample rates
SENTRY_SAMPLE_RATE=1.0           # Error sample rate (0-1)
SENTRY_TRACES_SAMPLE_RATE=0.1    # Performance sample rate (0-1)
```

### Using in Applications

```typescript
import { createSentryReporter } from '@yemaya/errors';

// Initialize Sentry
const sentry = createSentryReporter({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  release: process.env.npm_package_version,
  sampleRate: 1.0,
  tracesSampleRate: 0.1,
  debug: process.env.NODE_ENV === 'development',
});

// Capture an error
try {
  await riskyOperation();
} catch (error) {
  sentry.captureException(error, {
    userId: user.id,
    extra: { operation: 'riskyOperation' },
    tags: { module: 'payments' },
  });
}

// Capture a message
sentry.captureMessage('User signed up', 'info', {
  userId: user.id,
  extra: { plan: 'premium' },
});

// Add breadcrumb
sentry.addBreadcrumb({
  category: 'navigation',
  message: 'User navigated to dashboard',
  level: 'info',
  timestamp: new Date(),
});
```

### Express Middleware

```typescript
import express from 'express';
import {
  getSentryRequestHandler,
  getSentryTracingHandler,
  getSentryErrorHandler,
} from '@yemaya/errors';

const app = express();

// Request handler (must be first)
app.use(getSentryRequestHandler());

// Tracing handler (for performance monitoring)
app.use(getSentryTracingHandler());

// Your routes
app.use('/api', apiRouter);

// Error handler (must be before other error handlers)
app.use(getSentryErrorHandler());
```

## Projects

Create these projects in Sentry:

| Project          | Platform              | Description        |
| ---------------- | --------------------- | ------------------ |
| `yemaya-api`     | Node.js               | REST API service   |
| `yemaya-web`     | JavaScript (React)    | Web application    |
| `yemaya-desktop` | JavaScript (Electron) | Desktop app        |
| `yemaya-workers` | Node.js               | Background workers |

## Source Maps

### Build-Time Upload

Add to your build script:

```bash
# Install Sentry CLI
npm install -g @sentry/cli

# Upload source maps
sentry-cli releases new $VERSION
sentry-cli releases files $VERSION upload-sourcemaps ./dist
sentry-cli releases finalize $VERSION
```

### GitHub Actions

```yaml
- name: Upload source maps
  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: yemaya
    SENTRY_PROJECT: yemaya-api
```

### Webpack Plugin

```javascript
// webpack.config.js
const SentryWebpackPlugin = require('@sentry/webpack-plugin');

module.exports = {
  // ... other config
  plugins: [
    new SentryWebpackPlugin({
      include: './dist',
      ignore: ['node_modules'],
      release: process.env.npm_package_version,
    }),
  ],
};
```

## Error Grouping

### Custom Fingerprinting

```typescript
sentry.captureException(error, {
  extra: {
    // Custom fingerprint for grouping
    fingerprint: ['{{ default }}', error.code],
  },
});
```

### Issue Owner Rules

Configure in Sentry UI (Settings > Ownership Rules):

```
# API routes
path:apps/api/* #backend-team

# Web app
path:apps/web/* #frontend-team

# Authentication
tags.module:auth #security-team

# Payments
tags.module:payments #payments-team
```

## Alerting

### Slack Integration

1. Go to Settings > Integrations > Slack
2. Connect your Slack workspace
3. Create alert rules

### Email Alerts

1. Go to Settings > Alerts
2. Create new alert rule
3. Configure conditions and actions

### Alert Examples

**High Error Rate Alert**:

```
When: Number of events > 100 in 5 minutes
Notify: #alerts-errors, on-call@yemaya.io
```

**New Error Alert**:

```
When: First seen issue
Notify: #dev-team
```

**Regression Alert**:

```
When: Resolved issue reappears
Notify: Issue owner
```

## Performance Monitoring

### Transactions

```typescript
const transaction = sentry.startTransaction({
  name: 'POST /api/orders',
  op: 'http.server',
});

try {
  // Database query
  const dbSpan = transaction?.startChild({
    op: 'db.query',
    description: 'SELECT * FROM orders',
  });
  const orders = await db.query('SELECT * FROM orders');
  dbSpan?.finish();

  // External API call
  const apiSpan = transaction?.startChild({
    op: 'http.client',
    description: 'Payment gateway',
  });
  await paymentGateway.process();
  apiSpan?.finish();

  transaction?.setStatus('ok');
} catch (error) {
  transaction?.setStatus('internal_error');
  throw error;
} finally {
  transaction?.finish();
}
```

### Web Vitals

For web applications, enable automatic web vitals collection:

```typescript
import * as Sentry from '@sentry/browser';
import { BrowserTracing } from '@sentry/tracing';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  integrations: [new BrowserTracing()],
  tracesSampleRate: 0.1,
});
```

## Troubleshooting

### Events Not Appearing

1. Check DSN is correct:

   ```typescript
   console.log('Sentry DSN:', process.env.SENTRY_DSN);
   ```

2. Verify connectivity:

   ```bash
   curl -v http://localhost:9000/api/0/
   ```

3. Check for rate limiting:
   ```bash
   docker compose -f docker-compose.sentry.yml logs sentry-relay
   ```

### Source Maps Not Working

1. Ensure release matches:

   ```typescript
   console.log(
     'Release:',
     Sentry.getCurrentHub().getClient()?.getOptions().release
   );
   ```

2. Verify upload:

   ```bash
   sentry-cli releases files $VERSION list
   ```

3. Check paths match deployed paths

### High Memory Usage

1. Reduce retention in Settings > General
2. Scale ClickHouse:
   ```yaml
   sentry-clickhouse:
     deploy:
       resources:
         limits:
           memory: 4G
   ```

## Maintenance

### Database Cleanup

```bash
# Clean old data
docker compose -f docker-compose.sentry.yml exec sentry-web sentry cleanup --days 30

# Run scheduled cleanup
docker compose -f docker-compose.sentry.yml exec sentry-cron sentry cleanup --days 30
```

### Backup

```bash
# Backup PostgreSQL
docker compose -f docker-compose.sentry.yml exec sentry-postgres \
  pg_dump -U sentry sentry > sentry-backup.sql

# Backup ClickHouse
docker compose -f docker-compose.sentry.yml exec sentry-clickhouse \
  clickhouse-client --query "BACKUP DATABASE default TO '/backup/'"
```

## Related Documentation

- [@yemaya/errors Package](../packages/errors/README.md)
- [Logging](./LOGGING.md)
- [Monitoring](./MONITORING.md)
