GitHub - apvcode/pocketsentry: The 18MB drop-in Sentry alternative for self-hosters.

🌍 Read in: 🇬🇧 English | 🇷🇺 Русский

🇬🇧 English

🔥 The Problem

Self-hosting Sentry is an infrastructure nightmare:

You just wanted to catch a TypeError in your side project. Not deploy a distributed system.

💡 The Solution

PocketSentry is a single, self-contained binary that speaks the Sentry protocol. Your existing SDKs (sentry-python, @sentry/browser, sentry-go, etc.) connect to it without any code changes — just swap the DSN.

✨ Features

• 🔌 Drop-in compatible — works with official Sentry SDKs out of the box
• 📦 Single binary — templates embedded via go:embed, zero external files
• 🪶 Ultra-lightweight — ~18 MB binary, < 20 MB RAM at runtime
• 🗄️ Embedded SQLite — pure-Go driver (modernc.org/sqlite), no CGO hassle
• 🔄 Auto-deduplication — identical errors are grouped by (project, message, level) with a hit counter
• 📊 Real-time dashboard — dark-themed UI with HTMX auto-refresh (every 2s)
• 🔍 Detailed Stacktraces — Clickable rows to view full error details and raw JSON payloads
• 📈 Analytics & Filters — Interactive charts and instant HTMX filtering by error level
• 🛡️ Basic Auth — Built-in dashboard protection via username and password (ingestion API remains open)
• 🧹 Retention Policy — Background auto-cleanup of old events from the database
• 🔒 Graceful shutdown — SIGINT/SIGTERM → drain connections → close DB
• 🌐 Full CORS — browser SDKs work without proxy hacks
• 🗜️ Gzip support — transparent decompression of compressed payloads
• 🧩 Both endpoints — /api/{id}/store/ (legacy) and /api/{id}/envelope/ (modern)
• 🏥 Health Check — /health endpoint for uptime monitoring and orchestration
• 🔔 Webhooks — Instant error alerts in Telegram and Discord (only for new unique errors)
• 🛠️ Error Lifecycle — Resolve errors directly from the dashboard (automatically reopens if the error reoccurs)
• 📂 Project Management — Create isolated workspaces for your different apps and fetch dynamic DSNs
• 🗺️ Source Maps — Automatic demangling of minified JavaScript stacktraces via local .map files
• ⚡ Performance Monitoring — Track slow transactions with waterfall visualization of nested spans
• 👁️ Interactive Stacktraces — Prism.js syntax highlighting and toggle to collapse/expand third-party library frames
• 🍞 Breadcrumbs Timeline — Visual history of user actions (UI clicks, HTTP requests, console logs) preceding an error
• 🏷️ Release Tracking — Track errors associated with specific app versions (releases) with badges
• 🤖 Interactive Telegram Bot — Resolve errors directly from the Telegram chat with action buttons
• ⚙️ Notification Routing — Project-specific webhook target overrides (Discord/Telegram) for smart alerting
• 💬 Local Issue Notes — Add team comments and debugging notes directly to errors in the dashboard
• 🚀 Smart Resolving — Mark errors as "Resolved in Next Release" and let PocketSentry automatically detect regressions

🚀 Quick Start

1. Download and run:

Option A: Standalone Binary

./pocketsentry --port 8080

Option B: Docker

That's it. Open http://localhost:8080 to see the dashboard.

2. Point your SDK:

import sentry_sdk

sentry_sdk.init(
    dsn="http://public@localhost:8080/1",
    traces_sample_rate=0,
)

# Test it
raise ValueError("Hello from PocketSentry!")

const Sentry = require("@sentry/node");

Sentry.init({
  dsn: "http://public@localhost:8080/1",
});

// Test it
Sentry.captureException(new Error("Hello from PocketSentry!"));

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "http://public@localhost:8080/1",
});

// Test it
throw new Error("Hello from PocketSentry!");

import "github.com/getsentry/sentry-go"

func main() {
    sentry.Init(sentry.ClientOptions{
        Dsn: "http://public@localhost:8080/1",
    })
    defer sentry.Flush(2 * time.Second)

    sentry.CaptureMessage("Hello from PocketSentry!")
}

⚙️ CLI Options

Environment variables PORT and DB_PATH are also supported (flags take priority).

The server handles graceful shutdown: press Ctrl+C and it will finish in-flight requests, close the database, and exit cleanly.

$ ./pocketsentry --port 9090 --db /data/errors.db

   ___           _        _   ___            _
  | _ \ ___  __ | | __ __| |_/ __| ___ _ __ | |_ _ _ _  _
  |  _// _ \/ _|| |/ // _| __\__ \/ _ \ '_ \|  _| '_| || |
  |_|  \___/\__||_\_\\__|\__|___/\___/_||_|\__|_| \_, |
                                                   |__/
  ──────────────────────────────────────────────────
  🛡️  Version     : 3.2.0
  🌐 Dashboard   : http://localhost:9090
  📦 Database    : /data/errors.db
  🔗 DSN         : http://public@localhost:9090/1
  🔓 Auth        : disabled
  🗑️  Retention   : 30 days
  ──────────────────────────────────────────────────

  Point your Sentry SDK to the DSN above.
  Press Ctrl+C to stop.

🔨 Build from Source

git clone https://github.com/apvcode/pocketsentry.git
cd pocketsentry
go mod tidy
go build -o pocketsentry .
./pocketsentry

Requirements: Go 1.22+ (no CGO, no external C libraries).

🗺️ Roadmap

General Roadmap:

• ⚡ HTTP Latency Auto-Discovery via eBPF: Measure transaction response times (p50/p90/p99) directly in the Linux kernel without SDKs or changes to application code.
• 🔓 SSL/TLS Decryption via eBPF: Trace secure HTTPS connections by hooking SSL libraries (OpenSSL/Go TLS) at the kernel level.

📄 License

MIT — use it, fork it, ship it.

🇷🇺 Русский

🔥 Проблема

Самостоятельный хостинг Sentry — это инфраструктурный ад:

Ты просто хотел поймать TypeError в своём пет-проекте. А не деплоить распределённую систему.

💡 Решение

PocketSentry — это один автономный бинарник, который говорит на протоколе Sentry. Твои существующие SDK (sentry-python, @sentry/browser, sentry-go и др.) подключаются к нему без изменений в коде — просто замени DSN.

✨ Возможности

• 🔌 Drop-in совместимость — работает с официальными Sentry SDK из коробки
• 📦 Один бинарник — шаблоны встроены через go:embed, никаких внешних файлов
• 🪶 Ультралёгкий — ~18 МБ бинарник, < 20 МБ RAM в рантайме
• 🗄️ Встроенный SQLite — pure-Go драйвер (modernc.org/sqlite), без CGO
• 🔄 Авто-дедупликация — одинаковые ошибки группируются по (project, message, level) со счётчиком
• 📊 Дашборд реального времени — тёмная тема, HTMX автообновление каждые 2 секунды
• 🔍 Detailed Stacktraces — Кликабельные строки для просмотра детальной информации об ошибке и сырого JSON-пейлоада
• 📈 Analytics & Filters — Интерактивные графики и мгновенная фильтрация ошибок по уровням (HTMX)
• 🛡️ Basic Auth — Встроенная защита дашборда логином и паролем (API для приема логов остается открытым)
• 🧹 Retention Policy — Фоновая авто-очистка старых логов из базы данных
• 🔒 Graceful Shutdown — SIGINT/SIGTERM → дождаться запросов → закрыть БД
• 🌐 Полный CORS — браузерные SDK работают без проксирования
• 🗜️ Gzip — прозрачная декомпрессия сжатых payload'ов
• 🧩 Оба эндпоинта — /api/{id}/store/ (legacy) и /api/{id}/envelope/ (modern)
• 🏥 Health Check — эндпоинт /health для мониторинга аптайма и оркестрации
• 🔔 Уведомления — Мгновенные алерты об ошибках в Telegram и Discord (только для новых уникальных ошибок)
• 🛠️ Жизненный цикл ошибок — Возможность отмечать ошибки как «решенные» прямо из дашборда (автоматически переоткрываются, если баг повторится)
• 📂 Управление проектами — Создание отдельных воркспейсов для разных приложений со своими DSN.
• 🗺️ Source Maps — Автоматическая расшифровка минифицированных JS-ошибок (просто положите .map файлы в папку sourcemaps/).
• ⚡ Мониторинг производительности — Отслеживание медленных транзакций с визуализацией дерева спанов (Waterfall chart).
• 👁️ Интерактивные стек-трейсы — Подсветка синтаксиса (Prism.js) и скрытие системного кода (library frames) одной кнопкой.
• 🍞 Лента хлебных крошек — Визуальный таймлайн действий пользователя (клики, запросы, консоль лог) перед ошибкой.
• 🏷️ Отслеживание релизов — Отображение версии приложения для каждой ошибки с фиолетовыми бейджами релизов.
• 🤖 Интерактивный Telegram-бот — Решайте ошибки прямо из чата с помощью кнопок действий.
• ⚙️ Роутинг уведомлений — Указание индивидуальных Telegram/Discord вебхуков для каждого проекта.
• 💬 Локальные заметки — Оставляйте комментарии и заметки по дебагу прямо на странице ошибки.
• 🚀 Умный авто-резолв — Отмечайте баг как «решенный в следующем релизе», и система сама откроет его при регрессии.

🚀 Быстрый старт

1. Скачай и запусти:

Вариант А: Обычный бинарник

./pocketsentry --port 8080

Вариант Б: Docker

Всё! Открой http://localhost:8080 и смотри дашборд.

2. Подключи свой SDK:

import sentry_sdk

sentry_sdk.init(
    dsn="http://public@localhost:8080/1",
    traces_sample_rate=0,
)

# Проверка
raise ValueError("Привет от PocketSentry!")

const Sentry = require("@sentry/node");

Sentry.init({
  dsn: "http://public@localhost:8080/1",
});

// Проверка
Sentry.captureException(new Error("Привет от PocketSentry!"));

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "http://public@localhost:8080/1",
});

// Проверка
throw new Error("Привет от PocketSentry!");

import "github.com/getsentry/sentry-go"

func main() {
    sentry.Init(sentry.ClientOptions{
        Dsn: "http://public@localhost:8080/1",
    })
    defer sentry.Flush(2 * time.Second)

    sentry.CaptureMessage("Привет от PocketSentry!")
}

⚙️ Параметры CLI

🗺️ Поддержка Source Maps

PocketSentry умеет автоматически расшифровывать минифицированный JavaScript код из браузера, превращая его в читаемый исходный код с указанием реальных файлов и строк. Для этого используется максимально простой подход (без сложных загрузок через API):

1. Создайте папку sourcemaps рядом с бинарником (или примонтируйте её как Volume в Docker).
2. Положите туда ваши .map файлы (например, main.min.js.map).
3. При открытии ошибки сервер автоматически найдет карту, восстановит оригинальный код и подсветит нужную строчку в красивом блоке кода прямо в UI.

Также поддерживаются переменные окружения PORT и DB_PATH (флаги имеют приоритет).

Сервер поддерживает Graceful Shutdown: нажми Ctrl+C, и он корректно завершит текущие запросы, закроет базу данных и выйдет с кодом 0.

$ ./pocketsentry --port 9090 --db /data/errors.db

   ___           _        _   ___            _
  | _ \ ___  __ | | __ __| |_/ __| ___ _ __ | |_ _ _ _  _
  |  _// _ \/ _|| |/ // _| __\__ \/ _ \ '_ \|  _| '_| || |
  |_|  \___/\__||_\_\\__|\__|___/\___/_||_|\__|_| \_, |
                                                   |__/
  ──────────────────────────────────────────────────
  🛡️  Version     : 3.2.0
  🌐 Dashboard   : http://localhost:9090
  📦 Database    : /data/errors.db
  🔗 DSN         : http://public@localhost:9090/1
  🔓 Auth        : disabled
  🗑️  Retention   : 30 days
  ──────────────────────────────────────────────────

  Point your Sentry SDK to the DSN above.
  Press Ctrl+C to stop.

🔨 Сборка из исходников

git clone https://github.com/apvcode/pocketsentry.git
cd pocketsentry
go mod tidy
go build -o pocketsentry .
./pocketsentry

Требования: Go 1.22+ (без CGO, без внешних C-библиотек).

🗺️ Дорожная карта

Ближайшие планы:

• ⚡ Автоматический замер задержек через eBPF: Измерение времени ответа (p50/p90/p99) транзакций на уровне сетевого стека ядра Linux без SDK.
• 🔓 Расшифровка SSL/TLS трафика через eBPF: Перехват и трассировка защищенных соединений HTTPS с помощью eBPF uretprobes на OpenSSL и Go TLS.

📄 Лицензия

MIT — используй, форкай, шипь.