Eve library

Sentry Error Tracking

Guide

Revision 1

On this page

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):

text
# 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:

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

New Error Alert:

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

Regression Alert:

text
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/'"