Message Gateway

Приложение для отправки мониторинговых алертов из Grafana, Zabbix и AlertManager в мессенджеры (Telegram, MAX/VK) и создания тикетов в Jira.

Автор: Сергей Антропов
Сайт: https://devops.org.ru

Описание

Message Gateway - это микросервис, который принимает webhooks от систем мониторинга (Grafana, Zabbix, AlertManager) и отправляет уведомления в различные мессенджеры (Telegram, MAX/VK). Также поддерживает автоматическое создание тикетов в Jira на основе алертов. Поддерживает фильтрацию по стоп-словам, форматирование сообщений через Jinja2 шаблоны и интеграцию с Prometheus для сбора метрик.

Поддержка мессенджеров

• Telegram - Полная поддержка текстовых сообщений, медиа (фото, видео, аудио, документы) и тредов
• MAX/VK - Поддержка текстовых сообщений и медиа (треды не поддерживаются)

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

Подробная документация разделена на отдельные файлы в папке docs/:

Основная документация

• 📖 Настройка ботов - как создать ботов в Telegram и MAX/VK
• 📖 Конфигурация групп - как настроить группы мессенджеров
• 📖 Шаблоны сообщений - как работают шаблоны Jinja2
• 📖 Конфигурация Jira Mapping - как настроить маппинг алертов в Jira
• 📖 Отправка сообщений - как работает отправка сообщений

Настройка систем мониторинга

• 📖 Настройка Grafana - как настроить Grafana для отправки алертов
• 📖 Настройка Zabbix - как настроить Zabbix для отправки алертов
• 📖 Настройка AlertManager - как настроить AlertManager для отправки алертов

API документация

• 📖 API для управления группами - управление группами мессенджеров через API
• 📖 API для отправки сообщений - отправка простых сообщений в мессенджеры
• 📖 API для проверки здоровья - проверка здоровья и готовности приложения
• 📖 API для отладки - сохранение JSON данных для отладки
• 📖 Декораторы API - декораторы для авторизации и скрытия эндпоинтов

Возможности

• ✅ Отправка алертов из Grafana в мессенджеры (Telegram, MAX/VK)
• ✅ Отправка алертов из Zabbix в мессенджеры (Telegram, MAX/VK)
• ✅ Отправка алертов из AlertManager в мессенджеры (Telegram, MAX/VK)
• ✅ Поддержка отправки в треды Telegram (не поддерживается для MAX/VK)
• ✅ Поддержка нескольких мессенджеров (Telegram, MAX/VK)
• ✅ Отправка простых текстовых сообщений
• ✅ Отправка фото, видео, аудио и документов
• ✅ Управление группами мессенджеров (CRUD)
• ✅ Защита управления группами API ключом
• ✅ Автоматическое создание тикетов в Jira
• ✅ Настройка маппинга алертов в Jira тикеты
• ✅ Фильтрация по стоп-словам
• ✅ Форматирование сообщений через Jinja2 шаблоны
• ✅ Метрики Prometheus
• ✅ Интеграция с OpenTelemetry
• ✅ Кэширование конфигурации групп
• ✅ Асинхронная обработка запросов
• ✅ Валидация данных через Pydantic
• ✅ Подробное логирование

Требования

• Python 3.11+
• Docker и Docker Compose
• Telegram Bot Token (для Telegram)
• MAX/VK Access Token (для MAX/VK, опционально)
• Конфигурация групп мессенджеров (config/groups.json)
• Пароль для управления группами (опционально, для CRUD операций)
• Jira API Token (опционально, для интеграции с Jira)

Установка

1. Клонирование репозитория

git clone <repository-url>
cd message-gateway

2. Настройка переменных окружения

Создайте файл .env на основе .env.example:

cp env.example .env

Отредактируйте .env и укажите необходимые переменные:

# Telegram настройки
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
TELEGRAM_ENABLED=true

# MAX/VK настройки (опционально)
MAX_ACCESS_TOKEN=your_max_access_token_here
MAX_API_VERSION=5.131
MAX_ENABLED=false

# Общие настройки мессенджеров
DEFAULT_MESSENGER=telegram

# Настройки мониторинга
GRAFANA_URL=http://grafana.example.com
ZABBIX_URL=https://zabbix.example.com

# Jira настройки (опционально)
JIRA_ENABLED=false
JIRA_URL=https://jira.example.com
JIRA_EMAIL=user@example.com
JIRA_API_TOKEN=your_jira_api_token_here
JIRA_PROJECT_KEY=MON
JIRA_DEFAULT_ASSIGNEE=user@example.com
JIRA_DEFAULT_ISSUE_TYPE=Bug
JIRA_CREATE_ON_ALERT=true
JIRA_CREATE_ON_RESOLVED=false

3. Настройка конфигурации групп

Отредактируйте config/groups.json и добавьте группы мессенджеров.

📖 Подробная документация: Конфигурация групп

{
    "monitoring": {
        "messenger": "telegram",
        "chat_id": -1001234567890,
        "thread_id": 0,
        "config": {}
    },
    "alerts": {
        "messenger": "telegram",
        "chat_id": -1001234567891,
        "thread_id": 0,
        "config": {}
    },
    "max_alerts": {
        "messenger": "max",
        "chat_id": "123456789",
        "thread_id": null,
        "config": {
            "access_token": "optional_override_max_token"
        }
    }
}

Примечания:

• messenger - тип мессенджера (telegram, max) - обязательное поле
• chat_id - ID чата (может быть числом для Telegram или строкой для MAX/VK) - обязательное поле
• thread_id - ID треда в группе (только для Telegram, 0 для основной группы, null для MAX/VK)
• config - дополнительная конфигурация для мессенджера (например, access_token для MAX/VK)

4. Настройка конфигурации маппинга Jira

Отредактируйте config/jira_mapping.json и настройте маппинг алертов в Jira тикеты.

📖 Подробная документация: Конфигурация Jira Mapping

{
  "alertmanager": {
    "default_project": "MON",
    "default_assignee": null,
    "default_issue_type": "Bug",
    "default_priority": "High",
    "mappings": [
      {
        "conditions": {
          "severity": "critical",
          "namespace": "production"
        },
        "project": "MON",
        "assignee": null,
        "issue_type": "Bug",
        "priority": "Highest",
        "labels": ["critical", "production", "alertmanager"]
      }
    ]
  }
}

5. Запуск приложения

Использование Docker Compose

# Первый запуск (сборка и запуск)
make up-build

# Последующие запуски
make up

# Или напрямую через docker-compose
docker-compose up -d

Использование Makefile

make help      # Показать справку по всем командам
make build     # Собрать Docker образ
make up        # Запустить приложение
make up-build  # Собрать и запустить приложение (рекомендуется для первого запуска)
make logs      # Показать логи
make shell     # Открыть shell в контейнере
make down      # Остановить приложение
make status    # Показать статус контейнеров
make health    # Проверить здоровье приложения
make ready     # Проверить готовность приложения

Примечание: Все команды выполняются через Makefile. Скрипты .sh больше не используются и были удалены.

Подкоманды: Для удобства использования подкоманд (docker, git, k8s, env) доступны три варианта:

1. Через переменную CMD: make docker CMD=build
2. Напрямую: make docker-build
3. Через обертку: ./make-wrapper.sh docker build (для синтаксиса с пробелами)

Доступные команды:

Основные команды:

• make build - Собрать Docker образ
• make up - Запустить приложение
• make up-build - Собрать и запустить приложение (рекомендуется для первого запуска)
• make down - Остановить приложение
• make restart - Перезапустить приложение
• make logs - Показать логи приложения
• make shell - Открыть shell в контейнере
• make stop - Остановить приложение (alias для down)
• make status - Показать статус контейнеров
• make health - Проверить здоровье приложения
• make ready - Проверить готовность приложения

Разработка:

• make dev - Запустить в режиме разработки
• make test - Запустить тесты
• make lint - Запустить линтер
• make format - Форматировать код
• make install - Установить зависимости
• make clean - Очистить Docker образы и контейнеры
• make clean-all - Очистить все Docker ресурсы (включая volumes)

Docker команды:

• make docker CMD=build или make docker-build - Собрать Docker образ (без docker-compose)
• make docker CMD=tag или make docker-tag - Тегировать Docker образ для registry
• make docker CMD=push или make docker-push - Собрать, тегировать и отправить образ в registry
• make docker CMD=run или make docker-run - Запустить контейнер (без docker-compose)
• make docker CMD=stop или make docker-stop - Остановить контейнер (без docker-compose)
• make docker CMD=logs или make docker-logs - Показать логи контейнера (без docker-compose)
• make docker CMD=shell или make docker-shell - Открыть shell в контейнере (без docker-compose)
• ./make-wrapper.sh docker build - Альтернативный синтаксис через обертку

Git команды:

• make git CMD=status или make git-status - Показать статус репозитория
• make git CMD=pull или make git-pull - Получить изменения из удаленного репозитория
• make git CMD=push ARGS=origin main или make git-push - Отправить изменения в удаленный репозиторий
• make git CMD=add ARGS=file1 file2 или make git-add ARGS=file1 file2 - Добавить файлы в индекс
• make git CMD=commit ARGS="message" или make git-commit ARGS="message" - Создать коммит
• make git CMD=branch или make git-branch - Показать список веток
• ./make-wrapper.sh git status - Альтернативный синтаксис через обертку
• ./make-wrapper.sh git push origin main - Отправить изменения с аргументами

Kubernetes команды:

• make k8s CMD=contexts или make k8s-contexts - Показать доступные контексты
• make k8s CMD=set-context CONTEXT=prod или make k8s-set-context CONTEXT=prod - Установить контекст
• make k8s CMD=apply или make k8s-apply - Применить манифесты
• make k8s CMD=apply CONTEXT=prod - Применить манифесты с указанием контекста
• make k8s CMD=delete или make k8s-delete - Удалить ресурсы
• make k8s CMD=status или make k8s-status - Показать статус подов
• make k8s CMD=logs или make k8s-logs - Показать логи подов
• make k8s CMD=shell или make k8s-shell - Открыть shell в поде
• ./make-wrapper.sh k8s apply CONTEXT=prod - Альтернативный синтаксис через обертку

Env команды:

• make env CMD=check или make env-check - Проверить наличие .env файла
• make env CMD=create или make env-create - Создать .env файл из env.example
• make env CMD=create-force или make env-create-force - Принудительно создать .env файл (перезаписать существующий)
• ./make-wrapper.sh env check - Альтернативный синтаксис через обертку

Утилиты:

• make version - Показать версию проекта
• make psql - Подключиться к PostgreSQL (если используется)
• make redis-cli - Подключиться к Redis (если используется)

Использование

API Endpoints

📖 Подробная документация API:

• API для управления группами
• API для отправки сообщений
• API для проверки здоровья
• API для отладки

Мониторинг (без авторизации)

Все эндпоинты мониторинга объединены под тегом monitoring и не требуют авторизации:

• POST /api/v1/grafana/{group_name}/{thread_id} - Отправка алерта из Grafana
• POST /api/v1/zabbix/{group_name}/{thread_id} - Отправка алерта из Zabbix
• POST /api/v1/alertmanager/{k8s_cluster}/{group_name}/{thread_id} - Отправка алерта из AlertManager

📖 Подробная документация:

• Настройка Grafana
• Настройка Zabbix
• Настройка AlertManager

Примечание: Эндпоинты мониторинга объединены в один файл app/api/v1/endpoints/monitoring.py и используют общий тег monitoring в Swagger UI.

Управление группами (требуется API ключ)

• GET /api/v1/groups/messengers - Получить список поддерживаемых мессенджеров
• GET /api/v1/groups - Получить список групп (без API ключа - только названия, с API ключом - полная информация)
• POST /api/v1/groups - Создать группу
• PUT /api/v1/groups/{group_name} - Обновить группу
• DELETE /api/v1/groups/{group_name} - Удалить группу

📖 Подробная документация: API для управления группами

Отправка сообщений (требуется API ключ)

Все эндпоинты для отправки сообщений защищены декоратором @require_api_key и требуют API ключ в заголовке X-API-Key:

• POST /api/v1/message/text - Отправить текстовое сообщение
• POST /api/v1/message/photo - Отправить фото
• POST /api/v1/message/video - Отправить видео
• POST /api/v1/message/audio - Отправить аудио
• POST /api/v1/message/document - Отправить документ

Аутентификация:

• Все эндпоинты требуют заголовок X-API-Key: your_api_key_here
• API ключ настраивается в переменной окружения API_KEY в файле .env
• В Swagger UI доступна авторизация через кнопку "Authorize" (🔒)

📖 Подробная документация: API для отправки сообщений

Проверка здоровья (без авторизации)

• GET /api/v1/health - Проверка здоровья и готовности приложения

📖 Подробная документация: API для проверки здоровья

Отладка

• POST /api/v1/debug/dump - Сохранить JSON данные для отладки

📖 Подробная документация: API для отладки

Jira

Примечание: Создание тикетов в Jira происходит автоматически при получении алертов (внутренний процесс). API endpoints для создания тикетов вручную удалены в соответствии с требованиями.

📖 Подробная документация: Конфигурация Jira Mapping

Настройка Webhooks

📖 Подробная документация:

• Настройка Grafana
• Настройка Zabbix
• Настройка AlertManager

Интеграция с Jira

Настройка Jira

📖 Подробная документация: Конфигурация Jira Mapping

Примечание: Создание тикетов в Jira происходит автоматически при получении алертов (внутренний процесс). API endpoints для создания тикетов вручную удалены в соответствии с требованиями.

Стоп-слова

Приложение поддерживает фильтрацию алертов по стоп-словам. Алерты, содержащие следующие паттерны, не будут отправлены:

• InfoInhibitor
• Watchdog
• etcdHighCommitDurations
• etcdHighNumberOfFailedGRPCRequests
• kubePersistentVolumeFillingUp
• kubePersistentVolumeInodesFillingUp

Метрики Prometheus

Приложение отправляет метрики в Prometheus Pushgateway:

• tg_monitoring_gateway_api_endpoint_total - общее количество обращений к эндпоинтам API
• tg_monitoring_gateway_total_messages - всего сообщений получено
• tg_monitoring_gateway_sent_messages - сообщений успешно отправлено
• tg_monitoring_gateway_reject_messages - сообщений отклонено (стоп-слова)
• tg_monitoring_gateway_error_messages - ошибок отправки сообщений
• tg_monitoring_gateway_firing_messages - горящих алертов
• tg_monitoring_gateway_critical_messages - критических алертов
• tg_monitoring_gateway_resolved_messages - исправленных алертов
• tg_monitoring_gateway_jira_tickets_created - Jira тикетов создано
• tg_monitoring_gateway_jira_tickets_errors - ошибок создания Jira тикетов

Отправка простых сообщений

📖 Подробная документация: API для отправки сообщений

Приложение поддерживает отправку простых сообщений (текст, фото, видео, аудио, документы) в мессенджеры (Telegram, MAX/VK) без привязки к системам мониторинга.

Разработка

Запуск в режиме разработки

make dev

Запуск тестов

make test

Линтинг

make lint

Форматирование кода

make format

Просмотр всех доступных команд

make help

Проверка здоровья приложения

make health    # Проверить здоровье
make ready     # Проверить готовность

Управление Docker образами

# Использование через переменную CMD
make docker CMD=build    # Собрать образ
make docker CMD=tag      # Тегировать образ
make docker CMD=push     # Отправить образ в registry

# Или напрямую
make docker-build    # Собрать образ
make docker-tag      # Тегировать образ
make docker-push     # Отправить образ в registry

# Или через обертку
./make-wrapper.sh docker build
./make-wrapper.sh docker push

Работа с Git

# Использование через переменную CMD
make git CMD=status                    # Показать статус
make git CMD=pull                      # Получить изменения
make git CMD=push ARGS=origin main     # Отправить изменения
make git CMD=add ARGS=file1 file2      # Добавить файлы
make git CMD=commit ARGS="message"     # Создать коммит

# Или напрямую
make git-status
make git-pull
make git-push

# Или через обертку
./make-wrapper.sh git status
./make-wrapper.sh git push origin main
./make-wrapper.sh git commit "Update README"

Работа с Kubernetes

# Показать доступные контексты
make k8s CMD=contexts
# или
make k8s-contexts
# или
./make-wrapper.sh k8s contexts

# Установить контекст
make k8s CMD=set-context CONTEXT=prod
# или
make k8s-set-context CONTEXT=prod
# или
./make-wrapper.sh k8s set-context CONTEXT=prod

# Применить манифесты
make k8s CMD=apply
# или с указанием контекста
make k8s CMD=apply CONTEXT=prod
# или
make k8s-apply
# или
./make-wrapper.sh k8s apply CONTEXT=prod

# Показать статус подов
make k8s CMD=status
# или
make k8s-status

# Показать логи подов
make k8s CMD=logs
# или
make k8s-logs

# Открыть shell в поде
make k8s CMD=shell
# или
make k8s-shell

Работа с .env файлом

# Проверить наличие .env файла
make env CMD=check
# или
make env-check
# или
./make-wrapper.sh env check

# Создать .env файл из env.example
make env CMD=create
# или
make env-create
# или
./make-wrapper.sh env create

# Принудительно создать .env файл
make env CMD=create-force
# или
make env-create-force
# или
./make-wrapper.sh env create-force

Развертывание в Kubernetes

1. Создайте Secret с переменными окружения:

kubectl create secret generic message-gateway-secret \
  --from-literal=telegram_bot_token=your_token \
  --from-literal=grafana_url=http://grafana.example.com \
  --from-literal=jira_enabled=true \
  --from-literal=jira_url=https://jira.example.com \
  --from-literal=jira_email=user@example.com \
  --from-literal=jira_api_token=your_jira_api_token \
  -n message-gateway

2. Примените манифесты:

# Использование make
make k8s CMD=apply
# или с указанием контекста
make k8s CMD=apply CONTEXT=prod
# или напрямую
make k8s-apply
# или через обертку
./make-wrapper.sh k8s apply CONTEXT=prod

# Или напрямую через kubectl
kubectl apply -f kubernetes.yaml

Структура проекта

message-gateway/
├── app/
│   ├── api/
│   │   └── v1/
│   │       ├── endpoints/    # Эндпоинты API
│   │       │   ├── jira.py   # Эндпоинты Jira
│   │       │   ├── message.py # Эндпоинты для отправки сообщений
│   │       │   ├── groups.py # Эндпоинты для управления группами
│   │       │   └── ...
│   │       └── router.py     # Роутер API
│   ├── core/                 # Основные утилиты
│   │   ├── config.py         # Конфигурация
│   │   ├── telegram_client.py # Клиент Telegram
│   │   ├── jira_client.py    # Клиент Jira
│   │   ├── jira_mapping.py   # Управление маппингом Jira
│   │   ├── jira_utils.py     # Утилиты для работы с Jira
│   │   ├── groups.py         # Управление группами
│   │   ├── metrics.py        # Метрики Prometheus
│   │   └── utils.py          # Вспомогательные утилиты
│   ├── models/               # Модели Pydantic
│   │   ├── jira.py           # Модели Jira
│   │   ├── message.py        # Модели для отправки сообщений
│   │   ├── group.py          # Модели для управления группами
│   │   ├── grafana.py        # Модели Grafana
│   │   ├── zabbix.py         # Модели Zabbix
│   │   ├── alertmanager.py   # Модели AlertManager
│   │   └── ...
│   ├── modules/              # Модули обработки алертов
│   └── main.py               # Точка входа приложения
├── config/                   # Конфигурационные файлы
│   ├── groups.json           # Конфигурация групп Telegram
│   └── jira_mapping.json     # Конфигурация маппинга Jira
├── templates/                # Jinja2 шаблоны
│   ├── jira_common.tmpl      # Шаблон описания Jira тикета
│   └── ...
├── docker-compose.yaml       # Docker Compose конфигурация
├── Dockerfile                # Docker образ
├── Makefile                  # Makefile для управления проектом
├── make-wrapper.sh           # Обертка для поддержки подкоманд с пробелами
├── kubernetes.yaml           # Kubernetes манифесты
├── requirements.txt          # Python зависимости
├── env.example               # Пример файла окружения
└── README.md                 # Документация

Лицензия

Apache 2.0

Контакты

• Автор: Сергей Антропов
• Email: sergey@antropoff.ru
• Сайт: https://devops.org.ru