278 lines
10 KiB
Markdown
278 lines
10 KiB
Markdown
# GlitchUp Bot
|
||
|
||
Telegram-бот для GlitchTip, который:
|
||
|
||
- принимает webhook-алерты и отправляет их в Telegram;
|
||
- фильтрует окружения, делает dedup, mute по regex и мягкий rate limit;
|
||
- синхронизирует unresolved issues из GlitchTip API в локальный cache;
|
||
- строит digest, release summary и проектные сводки;
|
||
- поддерживает runtime-настройку ownership без рестарта через Telegram-команды;
|
||
- запускается локально через `uv` и в Docker через `docker compose`.
|
||
|
||
## Что сделано
|
||
|
||
В проекте уже реализовано:
|
||
|
||
- `POST /webhooks/glitchtip` для Slack-compatible payload из GlitchTip;
|
||
- Telegram polling с командами для просмотра сводок, релизов, sync-статуса и runtime-настроек;
|
||
- регулярный API sync в `issues_cache`;
|
||
- обновление `sync_state` для `api_sync` и `webhook`;
|
||
- release tracking через digest и команды `/releases`, `/release`;
|
||
- mute rules по regex с хранением в БД;
|
||
- rate limit для `P2`-алертов, при этом `P1` не режется;
|
||
- ownership overrides для project/topic/subscribers без рестарта;
|
||
- PostgreSQL + Alembic миграции;
|
||
- Docker-first запуск с авто-`alembic upgrade head`.
|
||
|
||
## Быстрый старт
|
||
|
||
### 1. Подготовить `.env`
|
||
|
||
Скопировать шаблон:
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
Заполнить минимум:
|
||
|
||
```env
|
||
TELEGRAM_BOT_TOKEN=your-bot-token
|
||
TELEGRAM_GROUP_CHAT_ID=-1001234567890
|
||
GLITCHTIP_URL=https://glitchtip.example.com
|
||
GLITCHTIP_API_TOKEN=your-token
|
||
GLITCHTIP_ORG_SLUG=your-org
|
||
DATABASE_URL=postgresql+asyncpg://glitchup:glitchup@db:5432/glitchup
|
||
```
|
||
|
||
Если хочешь ограничить админ-команды, укажи:
|
||
|
||
```env
|
||
TELEGRAM_ADMIN_IDS=123456789,987654321
|
||
```
|
||
|
||
Если список пустой, команды изменения конфигурации будут доступны всем.
|
||
|
||
### 2. Локальный запуск через `uv`
|
||
|
||
```bash
|
||
uv sync --dev
|
||
uv run alembic upgrade head
|
||
uv run glitchup-bot
|
||
```
|
||
|
||
Полезные команды разработки:
|
||
|
||
```bash
|
||
uv run pytest
|
||
uv run ruff check
|
||
uv run ruff format --check
|
||
uv run python -m glitchup_bot
|
||
```
|
||
|
||
### 3. Запуск через Docker
|
||
|
||
```bash
|
||
docker compose up --build
|
||
```
|
||
|
||
Что произойдёт:
|
||
|
||
- поднимется PostgreSQL;
|
||
- контейнер приложения выполнит `alembic upgrade head`;
|
||
- затем стартуют FastAPI, Telegram polling и scheduler.
|
||
|
||
Webhook endpoint:
|
||
|
||
```text
|
||
http://<host>:8080/webhooks/glitchtip
|
||
```
|
||
|
||
Healthcheck:
|
||
|
||
```text
|
||
http://<host>:8080/health
|
||
```
|
||
|
||
## Как пользоваться ботом
|
||
|
||
### Главное изменение интерфейса
|
||
|
||
Теперь ботом можно пользоваться не только командами, но и через inline-кнопки в Telegram:
|
||
|
||
- `/help` открывает экран поддержки и быстрых действий;
|
||
- `/admin` открывает админ-панель с основными управляющими действиями;
|
||
- для частых сценариев больше не нужно помнить все команды вручную.
|
||
|
||
### Обычный сценарий
|
||
|
||
1. Добавить бота в Telegram-группу.
|
||
2. Включить forum/topics режим в группе.
|
||
3. Создать топики:
|
||
backend alerts, frontend alerts, digest.
|
||
4. Узнать их `topic_id` и записать в `.env`.
|
||
5. Добавить webhook в GlitchTip на `POST /webhooks/glitchtip`.
|
||
6. При необходимости задать `WEBHOOK_SECRET` и тот же заголовок в GlitchTip.
|
||
7. После запуска бот начнёт:
|
||
- слать `P1/P2` алерты в Telegram;
|
||
- синхронизировать issues из API;
|
||
- строить digest и отвечать на команды.
|
||
8. Открой `/help`, чтобы пользоваться ботом через кнопки.
|
||
|
||
### Что делает бот в работе
|
||
|
||
- `P1`:
|
||
критичный production alert, отправляется сразу.
|
||
- `P2`:
|
||
production alert без критического цвета, отправляется сразу, но может быть ограничен rate limit.
|
||
- `P3`:
|
||
не шлётся realtime, остаётся в sync/digest-данных.
|
||
- Uptime alert:
|
||
идёт как `P1`.
|
||
|
||
### Основные команды
|
||
|
||
- `/help` — экран помощи, поддержки и быстрых кнопок.
|
||
- `/week` — digest за неделю.
|
||
- `/today` — новые issues за сегодня.
|
||
- `/project <slug>` — сводка по одному проекту.
|
||
- `/top` — самые шумные unresolved issues.
|
||
- `/stale` — самые старые unresolved issues.
|
||
- `/releases` — список релизов с незакрытыми issues.
|
||
- `/release <version>` — детали по конкретному релизу.
|
||
- `/sync_status` — время последней синхронизации.
|
||
- `/subscribe <backend|frontend>` — добавить себе runtime DM-подписку.
|
||
- `/unsubscribe <backend|frontend>` — убрать свою runtime DM-подписку.
|
||
|
||
### Админ-команды
|
||
|
||
- `/admin` — кнопочная админ-панель.
|
||
- `/sync` — принудительный sync cache.
|
||
- `/ownership` — показать текущие overrides.
|
||
- `/owner <slug> <backend|frontend>` — привязать проект к группе.
|
||
- `/owner_reset <slug>` — удалить runtime override проекта.
|
||
- `/topic <backend|frontend|digest> <topic_id>` — переопределить topic.
|
||
- `/topic_reset <backend|frontend|digest>` — снять topic override.
|
||
- `/mute_add <regex>` — добавить regex mute rule.
|
||
- `/mute_list` — показать mute rules.
|
||
- `/mute_del <id>` — удалить mute rule.
|
||
|
||
## Конфигурация
|
||
|
||
Основные переменные окружения:
|
||
|
||
```env
|
||
TELEGRAM_BOT_TOKEN=your-bot-token-here
|
||
TELEGRAM_GROUP_CHAT_ID=-1001234567890
|
||
TELEGRAM_ADMIN_IDS=123456789
|
||
|
||
TELEGRAM_BACKEND_TOPIC_ID=1
|
||
TELEGRAM_FRONTEND_TOPIC_ID=2
|
||
TELEGRAM_DIGEST_TOPIC_ID=3
|
||
|
||
BACKEND_PROJECTS=backend-production,backend-staging
|
||
FRONTEND_PROJECTS=frontend-production,frontend-staging
|
||
|
||
BACKEND_SUBSCRIBERS=123456789,987654321
|
||
FRONTEND_SUBSCRIBERS=
|
||
|
||
GLITCHTIP_URL=https://glitchtip.example.com
|
||
GLITCHTIP_API_TOKEN=your-token
|
||
GLITCHTIP_ORG_SLUG=your-org
|
||
|
||
DATABASE_URL=postgresql+asyncpg://glitchup:glitchup@db:5432/glitchup
|
||
|
||
API_PORT=8080
|
||
WEBHOOK_SECRET=
|
||
|
||
DIGEST_CRON_DAY=mon
|
||
DIGEST_CRON_HOUR=10
|
||
DIGEST_CRON_MINUTE=0
|
||
DIGEST_TIMEZONE=Asia/Krasnoyarsk
|
||
SYNC_INTERVAL_MINUTES=30
|
||
|
||
ALERT_ENVIRONMENTS=production
|
||
DEDUP_WINDOW_HOURS=6
|
||
ALERT_RATE_LIMIT_COUNT=10
|
||
ALERT_RATE_LIMIT_WINDOW_MINUTES=15
|
||
```
|
||
|
||
## Как это работает
|
||
|
||
### Webhook-контур
|
||
|
||
Для обычных issue-alert:
|
||
|
||
1. проверяется `X-Webhook-Secret`, если задан `WEBHOOK_SECRET`;
|
||
2. из attachment извлекается `Project`;
|
||
3. алерт фильтруется по `ALERT_ENVIRONMENTS`;
|
||
4. применяется dedup по fingerprint `project:title`;
|
||
5. `production + #e52b50` считается `P1`, остальное в production идёт как `P2`;
|
||
6. перед отправкой применяются mute rules;
|
||
7. для `P2` применяется rate limit по группе;
|
||
8. результат записывается в `notifications_sent`.
|
||
|
||
Для uptime-alert:
|
||
|
||
- сразу отправляется как `P1`;
|
||
- идёт в Telegram без обычного issue dedup.
|
||
|
||
### API sync
|
||
|
||
Sync:
|
||
|
||
- ходит в GlitchTip по всем проектам из конфигурации;
|
||
- upsert-ит unresolved issues в `issues_cache`;
|
||
- помечает пропавшие из unresolved issues как `resolved`;
|
||
- сохраняет release, regressions, event count, culprit и ссылки;
|
||
- обновляет `sync_state` для `api_sync`.
|
||
|
||
### Release tracking
|
||
|
||
- digest показывает блок "После релизов";
|
||
- `/releases` агрегирует issues по release;
|
||
- `/release <version>` показывает детали по одному релизу.
|
||
|
||
## Таблицы
|
||
|
||
Основные:
|
||
|
||
- `issues_cache` — кэш unresolved/resolved issues из API;
|
||
- `notifications_sent` — история alert/digest/uptime и статусы отправки;
|
||
- `sync_state` — состояние `api_sync` и `webhook`.
|
||
|
||
Runtime-настройки:
|
||
|
||
- `project_ownership_overrides` — project → group overrides;
|
||
- `group_topic_overrides` — topic overrides;
|
||
- `group_subscriber_overrides` — runtime subscriber overrides;
|
||
- `mute_rules` — regex mute rules.
|
||
|
||
## Тесты
|
||
|
||
```bash
|
||
uv run pytest
|
||
```
|
||
|
||
Покрыты базовые сценарии для:
|
||
|
||
- настроек;
|
||
- webhook endpoint;
|
||
- alert processor;
|
||
- digest builder;
|
||
- Telegram sender.
|
||
|
||
## Идеи и недоделки
|
||
|
||
Сейчас бот уже рабочий, но в этот блок вынесены идеи для следующих итераций:
|
||
|
||
- полноценный wizard-интерфейс в Telegram для изменения параметров без ручного ввода команд;
|
||
- отдельные команды для управления env-based подписчиками, а не только runtime overrides;
|
||
- более умный rate limit с burst/recovery-политикой и отдельной статистикой suppress-событий;
|
||
- mute rules с scope по проекту или группе, а не только глобальные regex;
|
||
- richer release analytics: сравнение "до/после релиза", отдельные regression-отчёты;
|
||
- отдельная admin-аутентификация вместо режима "если `TELEGRAM_ADMIN_IDS` пустой, можно всем";
|
||
- export/backup runtime-настроек ownership и mute rules;
|
||
- e2e-тесты с реальной БД и контейнерным прогоном;
|
||
- дополнительные команды для ручной диагностики sync и очередей уведомлений.
|