# Sentry Error Tracking

> Self-hosted error tracking and performance monitoring platform.

- Category: Monitoring & Observability
- Difficulty: advanced
- Components: sentry-web, sentry-worker, sentry-cron, postgresql, redis, kafka, clickhouse, snuba
- Tags: error-tracking, sentry, monitoring, apm, debugging
- Source: https://docker.recipes/monitoring/sentry-complete

## Overview

Sentry is an open-source application monitoring platform that provides real-time error tracking, performance monitoring, and release health insights for applications across multiple programming languages. Originally developed by Disqus in 2008 and later spun off as its own company, Sentry has become the de facto standard for error tracking in modern software development, offering both cloud-hosted and self-hosted solutions to help developers identify, diagnose, and resolve issues before they impact users. This comprehensive Docker stack combines Sentry's web interface, worker processes, and cron scheduler with a robust backend infrastructure including PostgreSQL for metadata storage, Redis for caching and session management, Apache Kafka for event streaming, ClickHouse for high-performance analytics, and Snuba as the query layer that bridges Sentry's data needs with ClickHouse's analytical capabilities. The architecture is specifically designed to handle high-throughput error ingestion and provide fast query performance for debugging workflows, making it suitable for organizations processing millions of events per day. This self-hosted deployment is ideal for teams requiring data sovereignty, custom integrations, or cost optimization compared to Sentry's cloud offering, while still maintaining the full feature set including error grouping, performance monitoring, release tracking, and team collaboration tools.

## Features

- Real-time error tracking with intelligent grouping and deduplication across multiple programming languages
- Performance monitoring with transaction traces, database query analysis, and web vitals tracking
- Release health monitoring with crash-free session rates and adoption tracking
- Source map support for JavaScript applications enabling readable stack traces in production
- Contextual breadcrumbs that capture user actions and system events leading up to errors
- Flexible alerting system with integrations for Slack, PagerDuty, Jira, and custom webhooks
- Session replay functionality for reproducing user sessions that encountered errors
- High-throughput event processing using Kafka for reliable message queuing and ClickHouse for analytical storage

## Use cases

- Enterprise organizations requiring self-hosted error tracking for compliance and data sovereignty
- Development teams processing high volumes of errors and performance data (>1M events/day)
- Companies wanting to avoid per-event pricing of cloud-hosted solutions
- Organizations with custom integration requirements for existing monitoring infrastructure
- Startups and scale-ups needing comprehensive debugging capabilities without vendor lock-in
- DevOps teams implementing observability strategies across microservices architectures
- Software companies providing error tracking as part of their platform offerings

## Prerequisites

- Minimum 8GB RAM for full stack deployment (Sentry requires 4GB+, ClickHouse needs 2GB+, Kafka 1GB+)
- 50GB+ available disk space for event storage and database growth
- Port 9000 available for Sentry web interface access
- Understanding of Sentry project configuration and SDK integration
- Familiarity with PostgreSQL database administration for backup and maintenance
- Basic knowledge of Kafka and ClickHouse for troubleshooting data pipeline issues

## docker-compose.yml

```yaml
services:
  sentry-web:
    image: getsentry/sentry:latest
    container_name: sentry-web
    environment:
      - SENTRY_SECRET_KEY=${SECRET_KEY}
      - SENTRY_POSTGRES_HOST=postgres
      - SENTRY_POSTGRES_PORT=5432
      - SENTRY_DB_NAME=sentry
      - SENTRY_DB_USER=sentry
      - SENTRY_DB_PASSWORD=${DB_PASSWORD}
      - SENTRY_REDIS_HOST=redis
      - SNUBA=http://snuba:1218
    volumes:
      - sentry-data:/data
    ports:
      - "9000:9000"
    depends_on:
      - postgres
      - redis
      - kafka
      - snuba
    networks:
      - sentry-network
    restart: unless-stopped

  sentry-worker:
    image: getsentry/sentry:latest
    container_name: sentry-worker
    command: run worker
    environment:
      - SENTRY_SECRET_KEY=${SECRET_KEY}
      - SENTRY_POSTGRES_HOST=postgres
      - SENTRY_DB_NAME=sentry
      - SENTRY_DB_USER=sentry
      - SENTRY_DB_PASSWORD=${DB_PASSWORD}
      - SENTRY_REDIS_HOST=redis
    volumes:
      - sentry-data:/data
    depends_on:
      - sentry-web
    networks:
      - sentry-network
    restart: unless-stopped

  sentry-cron:
    image: getsentry/sentry:latest
    container_name: sentry-cron
    command: run cron
    environment:
      - SENTRY_SECRET_KEY=${SECRET_KEY}
      - SENTRY_POSTGRES_HOST=postgres
      - SENTRY_DB_NAME=sentry
      - SENTRY_DB_USER=sentry
      - SENTRY_DB_PASSWORD=${DB_PASSWORD}
      - SENTRY_REDIS_HOST=redis
    volumes:
      - sentry-data:/data
    depends_on:
      - sentry-web
    networks:
      - sentry-network
    restart: unless-stopped

  postgres:
    image: postgres:15-alpine
    container_name: sentry-postgres
    environment:
      - POSTGRES_USER=sentry
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=sentry
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - sentry-network
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    container_name: sentry-redis
    volumes:
      - redis-data:/data
    networks:
      - sentry-network
    restart: unless-stopped

  kafka:
    image: confluentinc/cp-kafka:latest
    container_name: sentry-kafka
    environment:
      - KAFKA_ZOOKEEPER_CONNECT=zookeeper:2181
      - KAFKA_ADVERTISED_LISTENERS=PLAINTEXT://kafka:9092
      - KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR=1
    volumes:
      - kafka-data:/var/lib/kafka/data
    depends_on:
      - zookeeper
    networks:
      - sentry-network
    restart: unless-stopped

  zookeeper:
    image: confluentinc/cp-zookeeper:latest
    container_name: sentry-zookeeper
    environment:
      - ZOOKEEPER_CLIENT_PORT=2181
    volumes:
      - zookeeper-data:/var/lib/zookeeper/data
    networks:
      - sentry-network
    restart: unless-stopped

  clickhouse:
    image: clickhouse/clickhouse-server:latest
    container_name: sentry-clickhouse
    volumes:
      - clickhouse-data:/var/lib/clickhouse
    networks:
      - sentry-network
    restart: unless-stopped

  snuba:
    image: getsentry/snuba:latest
    container_name: sentry-snuba
    environment:
      - SNUBA_SETTINGS=docker
      - CLICKHOUSE_HOST=clickhouse
      - KAFKA_BOOTSTRAP_SERVERS=kafka:9092
    depends_on:
      - clickhouse
      - kafka
    networks:
      - sentry-network
    restart: unless-stopped

volumes:
  sentry-data:
  postgres-data:
  redis-data:
  kafka-data:
  zookeeper-data:
  clickhouse-data:

networks:
  sentry-network:
    driver: bridge
```

## .env

```bash
# Sentry
DB_PASSWORD=secure_sentry_password

# Generate with: python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
SECRET_KEY=your_sentry_secret_key
```

## Usage notes

- Sentry UI at http://localhost:9000
- Run migrations first: sentry upgrade
- Create admin: sentry createuser
- SDKs for all major languages
- Consider using official install script

## Troubleshooting

- Sentry web interface shows 'Internal Server Error': Check that database migrations have been run with 'docker exec sentry-web sentry upgrade' command
- Events not appearing in Sentry dashboard: Verify Snuba service is running and ClickHouse connection is established by checking snuba container logs
- High memory usage on ClickHouse container: Increase ClickHouse max_memory_usage setting or implement data retention policies to manage storage growth
- Kafka consumer lag warnings: Scale up sentry-worker instances or tune Kafka partition configuration for better throughput
- Redis connection errors in Sentry logs: Ensure Redis container has sufficient memory and check for Redis maxmemory-policy configuration
- Slow query performance in Sentry: Optimize ClickHouse table schemas and consider adjusting SNUBA_SETTINGS for your data volume

