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):
- Create organization at https://sentry.io
- Create projects for each service
- 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#
- Go to Settings > Integrations > Slack
- Connect your Slack workspace
- Create alert rules
Email Alerts#
- Go to Settings > Alerts
- Create new alert rule
- 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#
-
Check DSN is correct:
typescriptconsole.log('Sentry DSN:', process.env.SENTRY_DSN); -
Verify connectivity:
bashcurl -v http://localhost:9000/api/0/ -
Check for rate limiting:
bashdocker compose -f docker-compose.sentry.yml logs sentry-relay
Source Maps Not Working#
-
Ensure release matches:
typescriptconsole.log( 'Release:', Sentry.getCurrentHub().getClient()?.getOptions().release ); -
Verify upload:
bashsentry-cli releases files $VERSION list -
Check paths match deployed paths
High Memory Usage#
- Reduce retention in Settings > General
- 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/'"