153 lines
7.6 KiB
Markdown
153 lines
7.6 KiB
Markdown
# Matrix Alert Relay — Документация
|
||
|
||
## 1. Архитектура и структура проекта
|
||
Проект представляет собой HTTP-сервер (вебхук-релей), который принимает POST-запросы от систем мониторинга, парсит их, форматирует и отправляет в нужные комнаты Matrix.
|
||
|
||
**Основные файлы:**
|
||
- `matrix-relay.py` — точка входа. HTTP-сервер, принимающий запросы и маршрутизирующий их.
|
||
- `config.py` — глобальные настройки (адрес Homeserver, токен, порт).
|
||
- `rooms.py` — маппинг логических имен каналов (`disk`, `backup`, `docker`) на ID комнат Matrix.
|
||
- `alerts.py` — словарь `ALERTS_CONFIG` с описанием всех известных типов алертов.
|
||
- `grafana.py` — обработчик стандартных вебхуков от Grafana/Prometheus.
|
||
- `pbs.py` — обработчик специфичных вебхуков от Proxmox VE / Proxmox Backup Server.
|
||
- `formatters.py` — функции красивого форматирования текста для специфичных алертов.
|
||
- `matrix.py` — низкоуровневая отправка HTML-сообщений в Matrix API.
|
||
- `utils.py` — вспомогательные утилиты (экранирование HTML, форматирование байтов и т.д.).
|
||
|
||
---
|
||
|
||
## 2. Сценарий А: Добавление нового алерта (Grafana / Prometheus)
|
||
Если новый алерт приходит из Grafana или Prometheus, писать новый код парсинга не нужно. Достаточно обновить конфигурацию.
|
||
|
||
### Шаг 2.1. Добавление комнаты (если нужна новая)
|
||
Открой `rooms.py` и добавь новое имя канала и ID комнаты:
|
||
```python
|
||
CHANNELS = {
|
||
"default": "!WlzSAzmLQEATwDCaBU:matrix.zailon.ru",
|
||
"disk": "!wOlscPjqPWVbSHpYgc:matrix.zailon.ru",
|
||
"backup": "!ViUbvoFxTTbRLMtZEO:matrix.zailon.ru",
|
||
"ups": "!NewRoomId:matrix.zailon.ru",
|
||
}
|
||
```
|
||
|
||
### Шаг 2.2. Создание форматтера (опционально)
|
||
Если алерт требует особого вывода (например, вывод заряда батареи в процентах), открой `formatters.py`:
|
||
```python
|
||
def ups_battery(device, value=None):
|
||
if value is not None:
|
||
return f"🔋 {device:<8} {value}%"
|
||
return f"🔋 {device:<8}"
|
||
|
||
FORMATTERS = {
|
||
"temperature": temperature,
|
||
"ups_battery": ups_battery,
|
||
}
|
||
```
|
||
|
||
### Шаг 2.3. Регистрация алерта
|
||
Открой `alerts.py` и добавь новый ключ в `ALERTS_CONFIG`. Имя ключа должно точно совпадать с `alertname` из Grafana.
|
||
```python
|
||
ALERTS_CONFIG = {
|
||
"UPS Battery Low": {
|
||
"room": "ups",
|
||
"title": "🔋 Низкий заряд ИБП",
|
||
"summary": "⚡ Заряд батареи ИБП упал ниже критического.",
|
||
"info": "🔌 Проверьте питание и состояние ИБП.",
|
||
"resolved": "✅ Питание ИБП восстановлено.",
|
||
"formatter": "ups_battery",
|
||
"skip_zero_firing": False,
|
||
},
|
||
}
|
||
```
|
||
Релей автоматически подхватит новый алерт, отформатирует его и отправит в нужную комнату.
|
||
|
||
---
|
||
|
||
## 3. Сценарий Б: Добавление нового ИСТОЧНИКА алертов (кастомный вебхук)
|
||
Если новая система (например, Docker Events, Zabbix, или скрипт мониторинга UPS) шлет свой собственный JSON, не похожий на формат Grafana, нужно написать новый модуль.
|
||
|
||
### Шаг 3.1. Создание модуля-обработчика
|
||
Создай новый файл, например `ups.py` (по аналогии с `pbs.py`).
|
||
```python
|
||
import logging
|
||
from alerts.matrix import send_matrix
|
||
|
||
logger = logging.getLogger(__name__)
|
||
|
||
def process_ups_alert(obj: dict) -> None:
|
||
ups_name = obj.get("ups_name", "Unknown UPS")
|
||
battery_level = obj.get("battery", 0)
|
||
status = obj.get("status", "unknown")
|
||
|
||
if status == "critical":
|
||
text = f"<b>🚨 Критический разряд ИБП</b>\n\n"
|
||
text += f"🔋 <b>{ups_name}</b>\n"
|
||
text += f"📉 Осталось заряда: <b>{battery_level}%</b>\n"
|
||
text += "⚡ Срочно проверьте питание!"
|
||
room = "ups"
|
||
else:
|
||
text = f"<b>ℹ️ Статус ИБП</b>\n\n{ups_name}: {battery_level}%"
|
||
room = "default"
|
||
|
||
send_matrix(text, room)
|
||
```
|
||
|
||
### Шаг 3.2. Подключение обработчика в роутер
|
||
Открой `matrix-relay.py`. В методе `process_webhook` добавь условие для определения нового источника и вызови свою функцию.
|
||
```python
|
||
from alerts.ups import process_ups_alert
|
||
|
||
class WebhookHandler(BaseHTTPRequestHandler):
|
||
def process_webhook(self, obj: Dict) -> None:
|
||
if "ups_name" in obj:
|
||
logger.info("Processing UPS notification")
|
||
process_ups_alert(obj)
|
||
return
|
||
|
||
source = detect_backup_source(obj)
|
||
if source:
|
||
logger.info("Processing backup notification (source=%s)", source.value)
|
||
process_backup(obj, send_matrix, source)
|
||
return
|
||
|
||
if "alerts" in obj:
|
||
alerts = obj["alerts"]
|
||
logger.info("Processing Grafana alerts: %d items", len(alerts))
|
||
process_grafana({"alerts": alerts}, send_matrix)
|
||
return
|
||
|
||
logger.warning("Unknown webhook type")
|
||
send_matrix(
|
||
"<b>Webhook received</b><br><br><pre>" +
|
||
json.dumps(obj, ensure_ascii=False, indent=2) +
|
||
"</pre>"
|
||
)
|
||
```
|
||
Теперь при отправке POST-запроса на сервер с JSON `{"ups_name": "APC", "battery": 10, "status": "critical"}` алерт улетит в Matrix.
|
||
|
||
---
|
||
|
||
## 4. Шпаргалка по настройке вебхуков
|
||
- **URL для всех источников:** `http://<IP-сервера-manage>:8086/` (или `https://`, если стоит реверс-прокси).
|
||
- **Метод:** POST
|
||
- **Content-Type:** `application/json`
|
||
|
||
### Пример вызова из bash-скрипта (для Docker, UPS, Cron):
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8086/ \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"ups_name": "ServerRoom_UPS", "battery": 5, "status": "critical"}'
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Логирование и отладка
|
||
Все события пишутся в стандартный вывод. Если релей запущен через systemd, смотри логи:
|
||
```bash
|
||
journalctl -u matrix-relay -f
|
||
```
|
||
|
||
Если алерт пришел, но не обработался так, как ожидалось, ищи в логах строки:
|
||
- `Processing Grafana alerts` — релей распознал формат Grafana.
|
||
- `Processing backup notification` — релей распознал бэкап PVE/PBS.
|
||
- `Unknown webhook type` — релей не нашел знакомых ключей и отправил "сырой" JSON в комнату `default`. Используй это для отладки новых источников! |