Initial commit: Message Gateway project

- FastAPI приложение для отправки мониторинговых алертов в мессенджеры - Поддержка Telegram и MAX/VK - Интеграция с Grafana, Zabbix, AlertManager - Автоматическое создание тикетов в Jira - Управление группами мессенджеров через API - Декораторы для авторизации и скрытия эндпоинтов - Подробная документация в папке docs/ Автор: Сергей Антропов Сайт: https://devops.org.ru
2025-11-12 20:25:11 +03:00
commit b90def35ed
72 changed files with 10609 additions and 0 deletions
--- a/docs/monitoring/alertmanager.md
+++ b/docs/monitoring/alertmanager.md
@@ -0,0 +1,121 @@
+# Настройка AlertManager
+
+## Создание конфигурации AlertManager
+
+1. **Открытие конфигурации:**
+   - Откройте файл конфигурации AlertManager (обычно `alertmanager.yml`)
+   - Добавьте webhook receiver:
+
+```yaml
+receivers:
+  - name: 'message-gateway'
+    webhook_configs:
+      - url: 'http://your-gateway-url/api/v1/alertmanager/{k8s_cluster}/{group_name}/{thread_id}'
+        send_resolved: true
+        http_config:
+          bearer_token: 'optional-bearer-token'
+```
+
+2. **Настройка Route:**
+   - В конфигурации AlertManager добавьте route:
+
+```yaml
+route:
+  group_by: ['alertname', 'cluster', 'service']
+  group_wait: 10s
+  group_interval: 10s
+  repeat_interval: 12h
+  receiver: 'message-gateway'
+  routes:
+    - match:
+        severity: critical
+      receiver: 'message-gateway'
+      continue: true
+    - match:
+        severity: warning
+      receiver: 'message-gateway'
+```
+
+3. **Применение конфигурации:**
+   - Сохраните файл конфигурации
+   - Перезапустите AlertManager или перезагрузите конфигурацию:
+     ```bash
+     curl -X POST http://alertmanager:9093/-/reload
+     ```
+
+## Пример конфигурации
+
+**Полный пример `alertmanager.yml`:**
+```yaml
+global:
+  resolve_timeout: 5m
+
+route:
+  group_by: ['alertname', 'cluster', 'service']
+  group_wait: 10s
+  group_interval: 10s
+  repeat_interval: 12h
+  receiver: 'message-gateway'
+  routes:
+    - match:
+        severity: critical
+      receiver: 'message-gateway'
+      continue: true
+    - match:
+        severity: warning
+      receiver: 'message-gateway'
+
+receivers:
+  - name: 'message-gateway'
+    webhook_configs:
+      - url: 'http://message-gateway.example.com/api/v1/alertmanager/production/monitoring/0'
+        send_resolved: true
+```
+
+**Пример URL для webhook:**
+```
+http://message-gateway.example.com/api/v1/alertmanager/production/monitoring/0
+```
+
+Где:
+- `production` - имя Kubernetes кластера (используется для формирования URL к Grafana/Prometheus)
+- `monitoring` - имя группы из `config/groups.json`
+- `0` - ID треда (0 для основной группы, поддерживается только для Telegram)
+
+## Формат данных
+
+AlertManager отправляет данные в следующем формате:
+
+```json
+{
+  "status": "firing",
+  "externalURL": "http://alertmanager.example.com",
+  "commonLabels": {
+    "alertname": "HighCPUUsage",
+    "severity": "critical",
+    "namespace": "production",
+    "pod": "app-deployment-7d8f9b4c5-abc123",
+    "container": "app-container"
+  },
+  "commonAnnotations": {
+    "summary": "High CPU usage detected in production namespace",
+    "description": "CPU usage is above 90% for 5 minutes on pod app-deployment-7d8f9b4c5-abc123",
+    "runbook_url": "https://wiki.example.com/runbooks/high-cpu-usage"
+  }
+}
+```
+
+## Поддерживаемые статусы
+
+- `firing` - алерт сработал
+- `resolved` - алерт разрешен
+
+## Примечания
+
+- Не требует авторизации (API ключ не нужен)
+- Если Jira включена, будет автоматически создан тикет в Jira (внутренний процесс)
+- В сообщении будет добавлена кнопка для перехода к тикету в Jira (если поддерживается мессенджером)
+- Алерты могут быть заблокированы стоп-словами (настройка в config/stop_words.txt)
+- URL к Grafana/Prometheus/AlertManager формируется на основе имени кластера
+- Thread ID поддерживается только для Telegram (для MAX/VK игнорируется)
+
--- a/docs/monitoring/grafana.md
+++ b/docs/monitoring/grafana.md
@@ -0,0 +1,91 @@
+# Настройка Grafana
+
+## Создание Webhook Notification Channel
+
+1. **Открытие настроек:**
+   - Откройте Grafana и перейдите в раздел "Alerting" → "Notification channels"
+   - Нажмите "New channel"
+
+2. **Настройка webhook:**
+   - Выберите тип "Webhook"
+   - Заполните форму:
+     - **Name:** Message Gateway
+     - **Type:** webhook
+     - **URL:** `http://your-gateway-url/api/v1/grafana/{group_name}/{thread_id}`
+       - Где `{group_name}` - имя группы из `config/groups.json` (например, "monitoring")
+       - Где `{thread_id}` - ID треда (0 для основной группы, поддерживается только для Telegram)
+     - **HTTP Method:** POST
+     - **Send on all alerts:** включено
+     - **Include image:** опционально
+   - Сохраните настройки
+
+3. **Настройка Alert Rule:**
+   - Создайте или откройте существующее правило алерта
+   - В разделе "Notifications" выберите созданный канал "Message Gateway"
+   - Сохраните правило
+
+4. **Тестирование:**
+   - Создайте тестовый алерт в Grafana
+   - Проверьте, что сообщение пришло в Telegram/MAX
+
+**Пример URL для webhook:**
+```
+http://message-gateway.example.com/api/v1/grafana/monitoring/0
+```
+
+## Пример конфигурации
+
+**Notification Channel в Grafana:**
+- **Name:** Message Gateway
+- **Type:** Webhook
+- **URL:** `http://message-gateway.example.com/api/v1/grafana/monitoring/0`
+- **HTTP Method:** POST
+- **Send on all alerts:** Yes
+- **Include image:** No
+
+**Alert Rule:**
+- В разделе "Notifications" выберите "Message Gateway"
+- Сохраните правило
+
+## Формат данных
+
+Grafana отправляет данные в следующем формате:
+
+```json
+{
+  "title": "[Alerting] High CPU Usage",
+  "ruleId": 674180201771804383,
+  "ruleName": "High CPU Usage Alert",
+  "state": "alerting",
+  "evalMatches": [
+    {
+      "value": 95.5,
+      "metric": "cpu_usage_percent",
+      "tags": {"host": "server01", "instance": "production"}
+    }
+  ],
+  "orgId": 1,
+  "dashboardId": 123,
+  "panelId": 456,
+  "tags": {"severity": "critical", "environment": "production"},
+  "ruleUrl": "http://grafana.cism-ms.ru/alerting/list",
+  "message": "CPU usage is above 90% threshold for more than 5 minutes"
+}
+```
+
+## Поддерживаемые состояния
+
+- `alerting` - алерт сработал
+- `ok` - алерт разрешен
+- `paused` - алерт приостановлен
+- `pending` - алерт в ожидании
+- `no_data` - нет данных
+
+## Примечания
+
+- Не требует авторизации (API ключ не нужен)
+- Если Jira включена, будет автоматически создан тикет в Jira (внутренний процесс)
+- В сообщении будет добавлена кнопка для перехода к тикету в Jira (если поддерживается мессенджером)
+- URL правила алерта будет добавлен в сообщение
+- Thread ID поддерживается только для Telegram (для MAX/VK игнорируется)
+
--- a/docs/monitoring/zabbix.md
+++ b/docs/monitoring/zabbix.md
@@ -0,0 +1,107 @@
+# Настройка Zabbix
+
+## Создание Media Type
+
+1. **Открытие настроек:**
+   - Откройте Zabbix и перейдите в раздел "Administration" → "Media types"
+   - Нажмите "Create media type"
+
+2. **Настройка Media Type:**
+   - Заполните форму:
+     - **Name:** Message Gateway
+     - **Type:** Webhook
+     - **Script name:** message-gateway
+     - **Script parameters:**
+       ```
+       {ALERT.SENDTO}
+       {ALERT.SUBJECT}
+       {ALERT.MESSAGE}
+       ```
+   - Сохраните настройки
+
+3. **Создание Action:**
+   - Перейдите в раздел "Configuration" → "Actions" → "Trigger actions"
+   - Нажмите "Create action"
+   - Заполните форму:
+     - **Name:** Send to Message Gateway
+     - **Conditions:** выберите условия (например, "Trigger severity" = "High")
+     - **Operations:** добавьте операцию "Send to Message Gateway"
+     - **Recovery operations:** добавьте операцию "Send to Message Gateway"
+   - Сохраните настройки
+
+4. **Настройка User Media:**
+   - Откройте пользователя в Zabbix
+   - В разделе "Media" добавьте новый media:
+     - **Type:** Message Gateway
+     - **Send to:** `monitoring/0` (формат: `{group_name}/{thread_id}`)
+     - **When active:** 1-7,00:00-24:00
+   - Сохраните настройки
+
+## Пример конфигурации
+
+**Media Type в Zabbix:**
+- **Name:** Message Gateway
+- **Type:** Webhook
+- **Script name:** message-gateway
+- **Script parameters:**
+  ```
+  {ALERT.SENDTO}
+  {ALERT.SUBJECT}
+  {ALERT.MESSAGE}
+  ```
+
+**Action:**
+- **Name:** Send to Message Gateway
+- **Conditions:** Trigger severity = High
+- **Operations:** Send to Message Gateway
+- **Recovery operations:** Send to Message Gateway
+
+**User Media:**
+- **Type:** Message Gateway
+- **Send to:** `monitoring/0`
+- **When active:** 1-7,00:00-24:00
+
+## Формат данных
+
+Zabbix отправляет данные в следующем формате:
+
+```json
+{
+  "link": "https://zabbix.example.com/tr_events.php?triggerid=42667&eventid=8819711",
+  "status": "PROBLEM",
+  "action-id": "7",
+  "alert-subject": "Problem: High CPU utilization (over 90% for 5m)",
+  "alert-message": "Problem started at 16:48:44 on 2024.02.08",
+  "event-id": "8819711",
+  "event-name": "High CPU utilization (over 90% for 5m)",
+  "event-nseverity": "2",
+  "event-opdata": "Current utilization: 95.2 %",
+  "event-severity": "Warning",
+  "host-name": "pnode28",
+  "host-ip": "10.14.253.38",
+  "host-port": "10050"
+}
+```
+
+## Поддерживаемые статусы
+
+- `PROBLEM` - проблема обнаружена
+- `OK` - проблема разрешена
+
+## Уровни серьезности
+
+- `Disaster` - катастрофа
+- `High` - высокая
+- `Warning` - предупреждение
+- `Average` - средняя
+- `Information` - информация
+
+## Примечания
+
+- Не требует авторизации (API ключ не нужен)
+- Если Jira включена, будет автоматически создан тикет в Jira (внутренний процесс)
+- В сообщении будет добавлена кнопка для перехода к тикету в Jira (если поддерживается мессенджером)
+- Ссылка на событие Zabbix будет добавлена в сообщение
+- Thread ID поддерживается только для Telegram (для MAX/VK игнорируется)
+- Можно настроить фильтрацию по серьезности события
+