Sentry Integration

This proposal details the design, configuration, and alerting strategy for deploying Sentry across all microservices running on AWS ECS to provide centralized error monitoring and performance tracking.

Objective & Challenges

Objective

Implement real-time error tracking and exception monitoring across services to increase release confidence and reduce Mean Time to Resolution (MTTR).

Current Challenges

• Silent exceptions: Exceptions are unnoticed until reported by end users.
• Log fragmentation: Troubleshooting requires searching across multiple, disjointed service logs.
• Release correlation: Identifying which deployment introduced a new error is difficult.
• Limited failure context: Stack traces and request metadata are not easily accessible during incidents.

Proposed Solution

We integrate the Sentry SDK into all application services to aggregate errors, visualize stack traces, track release health, and trigger alerts.

High-Level Architecture

Components

1. Sentry SDK
   • Integrated into each ECS service to capture unhandled exceptions, performance transactions, and request metadata, and associate them with releases.
2. Sentry Platform
   • Groups duplicate errors, visualizes stack traces with source maps, manages issue states, and displays release health metrics.
3. Alerting Integration
   • Configured to dispatch immediate alerts to Slack, Microsoft Teams, Email, or PagerDuty on critical failures.

Deployment Options

Option 1 — Sentry SaaS (Recommended)

Utilize the cloud-hosted Sentry platform.

• Benefits: Zero infrastructure management, automatic updates, built-in scalability, and rapid setup.

Option 2 — Self-Hosted Sentry

Deploy Sentry within our AWS VPC infrastructure.

• Benefits: Full control of telemetry data and internal data residency.
• Challenges: High operational overhead, database management (PostgreSQL, ClickHouse, Redis), upgrade maintenance, and additional infrastructure costs.

Application Integration

Sentry SDK Configuration

Inject the following variables into each ECS task definition:

SENTRY_DSN=<project-dsn>
SENTRY_ENVIRONMENT=production
SENTRY_RELEASE=<application-version>

To enable clean issue filtering, services must adopt a standardized naming convention:

• api-gateway
• auth-service
• user-service
• payment-service
• notification-service

Error & Performance Monitoring

• Unhandled Exceptions: Sentry automatically hooks into the runtime to capture crashes, TypeError, NullPointerException, or RuntimeException.
• Handled Exceptions: Send validation or external API errors explicitly:

  try {
    await chargeCard(amount);
  } catch (error) {
    Sentry.captureException(error, { tags: { type: "payment_failure" } });
  }

• Performance Monitoring: Tracks transaction durations, database queries, and external API requests:

  User Request
  ├── Authentication (80ms)
  ├── Database Query (45ms)
  ├── External API Call (210ms)
  └── Response (335ms)

Alerting Strategy

Critical Alerts

Trigger alerts for the failures that most directly affect users and revenue:

• Application crashes
• High error rates
• Authentication failures
• Payment processing failures

Notification Channels

Expected Benefits

• Faster incident detection — immediate visibility into application failures with automated notifications.
• Improved troubleshooting — detailed stack traces, root cause visibility, and error grouping.
• Release confidence — detect issues introduced by deployments and monitor release stability.
• Reduced MTTR — faster identification and remediation of issues.

Implementation Plan

Phase 1 — SDK & Alerting Integration

1. Create Sentry Organization: Initialize the organization, define projects per service, and configure environments (Alpha, Beta, Production).
2. Integrate SDK: Add Sentry SDK dependencies to all five core services.
3. Configure Alerting: Set up Slack/Email notification rules.
4. Validate: Generate dummy exceptions to verify end-to-end ingestion and alert delivery.

Phase 2 — Performance Monitoring

Enable transaction sampling rates to capture service transaction durations and identify latency bottlenecks.

Phase 3 — OpenTelemetry Integration

Link OpenTelemetry traces with Sentry errors. This combination allows engineers to click a Sentry error and view the exact distributed trace path in Tempo or Axiom.

OpenTelemetry provides request tracing while Sentry provides error monitoring — together they improve troubleshooting efficiency.