MessageGateway/README.md

# 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/`](docs/):

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

- 📖 [Настройка ботов](docs/bots.md) - как создать ботов в Telegram и MAX/VK
- 📖 [Конфигурация групп](docs/groups.md) - как настроить группы мессенджеров
- 📖 [Шаблоны сообщений](docs/templates.md) - как работают шаблоны Jinja2
- 📖 [Конфигурация Jira Mapping](docs/jira-mapping.md) - как настроить маппинг алертов в Jira
- 📖 [Отправка сообщений](docs/messaging.md) - как работает отправка сообщений

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

- 📖 [Настройка Grafana](docs/monitoring/grafana.md) - как настроить Grafana для отправки алертов
- 📖 [Настройка Zabbix](docs/monitoring/zabbix.md) - как настроить Zabbix для отправки алертов
- 📖 [Настройка AlertManager](docs/monitoring/alertmanager.md) - как настроить AlertManager для отправки алертов

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

- 📖 [API для управления группами](docs/api/groups.md) - управление группами мессенджеров через API
- 📖 [API для отправки сообщений](docs/api/message.md) - отправка простых сообщений в мессенджеры
- 📖 [API для проверки здоровья](docs/api/health.md) - проверка здоровья и готовности приложения
- 📖 [API для отладки](docs/api/debug.md) - сохранение JSON данных для отладки
- 📖 [Декораторы API](docs/api/decorators.md) - декораторы для авторизации и скрытия эндпоинтов

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

- ✅ Отправка алертов из 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. Клонирование репозитория

```bash
git clone <repository-url>
cd message-gateway
```

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

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

```bash
cp env.example .env
```

Отредактируйте `.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` и добавьте группы мессенджеров.

> 📖 **Подробная документация:** [Конфигурация групп](docs/groups.md)

```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](docs/jira-mapping.md)

```json
{
  "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

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

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

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

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

```bash
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 для управления группами](docs/api/groups.md)
> - [API для отправки сообщений](docs/api/message.md)
> - [API для проверки здоровья](docs/api/health.md)
> - [API для отладки](docs/api/debug.md)

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

Все эндпоинты мониторинга объединены под тегом `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](docs/monitoring/grafana.md)
> - [Настройка Zabbix](docs/monitoring/zabbix.md)
> - [Настройка AlertManager](docs/monitoring/alertmanager.md)

**Примечание:** Эндпоинты мониторинга объединены в один файл `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 для управления группами](docs/api/groups.md)

#### Отправка сообщений (требуется 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 для отправки сообщений](docs/api/message.md)

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

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

> 📖 **Подробная документация:** [API для проверки здоровья](docs/api/health.md)

#### Отладка

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

> 📖 **Подробная документация:** [API для отладки](docs/api/debug.md)

#### Jira

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

> 📖 **Подробная документация:** [Конфигурация Jira Mapping](docs/jira-mapping.md)

### Настройка Webhooks

> 📖 **Подробная документация:** 
> - [Настройка Grafana](docs/monitoring/grafana.md)
> - [Настройка Zabbix](docs/monitoring/zabbix.md)
> - [Настройка AlertManager](docs/monitoring/alertmanager.md)

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

### Настройка Jira

> 📖 **Подробная документация:** [Конфигурация Jira Mapping](docs/jira-mapping.md)

**Примечание:** Создание тикетов в 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 для отправки сообщений](docs/api/message.md)

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

## Разработка

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

```bash
make dev
```

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

```bash
make test
```

### Линтинг

```bash
make lint
```

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

```bash
make format
```

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

```bash
make help
```

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

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

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

```bash
# Использование через переменную 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

```bash
# Использование через переменную 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

```bash
# Показать доступные контексты
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 файлом

```bash
# Проверить наличие .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 с переменными окружения:

```bash
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. Примените манифесты:

```bash
# Использование 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