Gotcha

Документация

Gotcha — self-hosted-платформа наблюдаемости в одном Go-бинарнике: ошибки, аптайм, трейсы, метрики и профили на вашем сервере, без внешних сервисов и без передачи данных третьим лицам. Документация покрывает весь путь — от первого docker compose up до тонкой настройки продакшена, резервного копирования и обновлений.

С чего начать:

  • Установка — системные требования, docker compose, первый запуск;
  • Первые шаги — организация, проект, первое событие и первый монитор;
  • SDK и интеграции — подключение Sentry-совместимых SDK и OpenTelemetry (OTLP).

Если вы переезжаете с Sentry, отдельный разбор есть в блоге: как перейти с Sentry на self-hosted Gotcha. Полное оглавление — ниже, по разделам.

Начало

  • Первые шаги — Gotcha — платформа наблюдаемости: ошибки, производительность, метрики, аптайм и оповещения в одном месте. Она говорит на протоколе приёма Sentry, поэтому под…
  • Ключи приёма — Каждый проект принимает телеметрию по DSN-ключу — публичной строке, которая одновременно называет проект и разрешает слать в него данные (см. Термины). У клю…
  • Термины — Короткий словарь понятий Gotcha — от организаций и проектов до профилей и квот. Там, где у термина есть отдельная страница с подробностями, дана ссылка.
  • Окно времени — У каждой страницы с графиком — Производительность и страница эндпойнта, Web Vitals, Метрики, Профили, график задержек монитора и график частоты проблемы — об…

Установка и эксплуатация

  • Установка — Эта инструкция рассчитана на то, что вы никогда раньше не разворачивали Docker-приложения и не администрировали Linux-сервер. Все команды даны в готовом для…
  • Конфигурация — Gotcha полностью настраивается переменными окружения с префиксом GOTCHA_. Ни одного конфиг-файла, ни одной настройки через веб-интерфейс для системных параме…
  • Усиление установки — Базовый чек-лист продакшена — в Установке, таблица переменных HSTS и их взаимные ограничения — в Конфигурации (секция Security). Эта страница — свод: что из…
  • Резервное копирование и восстановление — Gotcha хранит данные в двух разных базах, и обе одинаково важны — резервную копию нужно снимать из обеих сразу, иначе после восстановления они разойдутся (на…
  • Обновление — Обновление применяет миграции схемы баз данных — это необратимо (обратных миграций «на всякий случай» никто не запускает автоматически). Прежде чем обновлять…
  • Политика версионирования — До версии 1.0 gotcha меняет контракт между релизами свободно — рабочие инструкции меняются в обновлении от версии к версии. С 1.0 это кончается: часть контра…
  • Мониторинг самого gotcha — gotcha следит за вашими сервисами. Эта страница — о том, как следить за самим gotcha: что он рассказывает о своём здоровье и куда смотреть, если вы подозрева…
  • Кардинальность: почему часть имён сгруппирована — Если на странице производительности или метрик вы увидели предупреждение о лимите различных значений, а в списке появилось <cardinality-limit> — эта страница…

Разделы

  • Обзор — Экран «Обзор» — точка входа в проект: одна шкала того, что сломано прямо сейчас и что недавно починилось, собранная по всем источникам инцидентов сразу — хос…
  • Проблемы — Проблемы создаются автоматически из событий, которые присылает SDK вашего приложения — Gotcha принимает их по протоколу приёма Sentry (envelope/store), так ч…
  • Выгрузки — Заявка на файл со списком ошибок или сырых событий проекта — CSV, JSON или NDJSON, собирается в фоне и ждёт скачивания на странице /projects/{id}/exports.
  • Производительность — Раздел «Производительность» показывает не отдельные ошибки, а то, как быстро работает приложение: транзакции (обработанные запросы или фоновые операции), из…
  • Зависимости — Экран «Зависимости» показывает, с чем *взаимодействует* ваш сервис вовне — базы данных, кеши и другие HTTP-сервисы, которые он вызывает, — с числом вызовов,…
  • Деплои — Летопись ваших выкладок: каждый деплой, о котором сообщает CI, появляется вертикальным маркером на графиках проекта, в отдельном списке и рядом с регрессиями…
  • SLO и бюджеты ошибок — число, за которое можно отвечать: *99% запросов успешны за последние 30 дней*. Gotcha непрерывно считает это число по уже собираемой телеметрии, показывает,…
  • Метрики — Раздел «Метрики» хранит числовые временные ряды, которые ваше приложение отправляет по протоколу OTLP (OpenTelemetry Protocol). Это отдельный канал приёма —…
  • Рецепты мониторинга — Раздел «Рецепты» — готовое подключение мониторинга типовых сервисов: PostgreSQL, MariaDB, nginx, Redis и Docker. Один рецепт — это страница со всем, что нужн…
  • Оповещения по метрикам — Правило оповещения по метрике следит за агрегатом метрики (avg/max/p95 и т. п.) на скользящем окне времени и открывает инцидент, когда значение пробивает зад…
  • Хосты — Раздел «Хосты» показывает системные метрики серверов, на которых крутится ваше приложение: CPU, память, диск, сеть, нагрузку (load average) и число процессов…
  • Логи — Раздел телеметрии для структурированных логов приложения: приём через API (описан ниже) и экран просмотра/поиска в интерфейсе.
  • Профилирование — Gotcha принимает профили двумя разными путями.
  • Аптайм — Раздел «Аптайм» следит за доступностью внешних адресов и сервисов через периодические проверки — мониторы. Открывается по значку с активностью в левой рельсе…
  • Публичные статус-страницы — Публичная статус-страница — витрина состояния выбранных мониторов проекта: отдельная страница без входа в систему, на которую можно давать ссылку пользовател…
  • Окна обслуживания — Окно обслуживания — заранее объявленный интервал плановых работ проекта. Пока оно активно, инциденты, открывшиеся у мониторов этого проекта, помечаются как «…
  • Пробы (удалённые регионы) — Проба — это отдельный процесс gotcha, запущенный в режиме --mode=probe, который выполняет проверки мониторов из своей точки сети (другой город, дата-центр, о…
  • Оповещения — Раздел «Оповещения» связывает правила с каналами доставки, чтобы команда узнавала о новых проблемах, регрессиях и всплесках без постоянного мониторинга дашбо…
  • Эскалации — Эскалация — это лесенка ступеней уведомления: чем дольше инцидент остаётся открытым и неподтверждённым, тем шире круг каналов, куда уходит уведомление. Разде…
  • Подавление шторма — Когда падает узел, от которого зависят другие (шлюз, гипервизор, база), каждый зависимый узел молчит или начинает сыпать собственными алертами — дежурный пол…
  • Группы инцидентов — Когда падает узел, от которого зависят другие (шлюз, гипервизор, база), сигналы сыплются со всех сторон: молчат хосты за шлюзом, срабатывают metric-пороги, г…

Администрирование

  • Организации, проекты и команды — Роль назначается на уровне организации и действует на все её проекты:
  • SSO и вход через провайдеров — Помимо пароля, Gotcha умеет входить через внешних провайдеров: универсальный OIDC (любой совместимый IdP — Keycloak, Authentik, Auth0 и т.п.), Яндекс ID и VK…
  • Приватность и 152-ФЗ — Gotcha — self-hosted-платформа: вы разворачиваете её на своей инфраструктуре и сами распоряжаетесь всеми данными. Это значит, что в терминах Федерального зак…

Интеграции

  • SDK и интеграции — Gotcha не имеет собственного протокола отправки данных — она принимает события и транзакции по протоколу приёма Sentry, а метрики и профили — по OTLP и pprof…