299 lines
10 KiB
Markdown
299 lines
10 KiB
Markdown
# ZONT Prometheus Exporter
|
||
|
||
Экспортер метрик для устройств **ZONT** и **Mega SX** в формате, совместимом с **Prometheus**. Позволяет собирать данные о температуре, состоянии котла, уровне сигнала, охране и других параметрах через официальный API ZONT.
|
||
|
||
## 📋 Возможности
|
||
|
||
- 🔐 Аутентификация через официальный API ZONT (`my.zont.online/api`)
|
||
- 🌡️ Сбор температуры с проводных и радиодатчиков
|
||
- 🔥 Мониторинг работы котла (время работы, аварии)
|
||
- 📶 Уровень сигнала GSM/Wi-Fi
|
||
- 🛡️ Состояние охраны и сирены
|
||
- 🚗 Данные об автомобиле (ZTC): зажигание, двигатель, автозапуск
|
||
- 🐳 Готов к запуску в Docker
|
||
- ⚙️ Полностью настраивается через переменные окружения
|
||
- 🩺 Встроенный healthcheck
|
||
|
||
## 🚀 Быстрый старт
|
||
|
||
### 1. Клонирование проекта
|
||
|
||
```bash
|
||
git clone <ваш-репозиторий>/zont-exporter.git
|
||
cd zont-exporter
|
||
```
|
||
|
||
### 2. Настройка окружения
|
||
|
||
Создайте файл `.env` на основе примера и заполните своими данными:
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
nano .env
|
||
```
|
||
|
||
Пример содержимого `.env`:
|
||
|
||
```env
|
||
ZONT_LOGIN=ваш_логин
|
||
ZONT_PASSWORD=ваш_пароль
|
||
ZONT_CLIENT_EMAIL=ваш@email.com
|
||
SCRAPE_INTERVAL=60
|
||
EXPORTER_PORT=8000
|
||
LOG_LEVEL=INFO
|
||
```
|
||
|
||
> ⚠️ **Важно**: `ZONT_CLIENT_EMAIL` — это контактный email, который вы указали при регистрации в ZONT. Он передаётся в заголовке `X-ZONT-Client` и используется производителем для связи с вами при изменениях в API.
|
||
|
||
### 3. Запуск
|
||
|
||
#### Вариант A: Docker Compose (рекомендуется)
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
#### Вариант B: Docker build + run
|
||
|
||
```bash
|
||
docker build -t zont-exporter:latest .
|
||
|
||
docker run -d \
|
||
--name zont-exporter \
|
||
--restart unless-stopped \
|
||
--env-file .env \
|
||
-p 8000:8000 \
|
||
zont-exporter:latest
|
||
```
|
||
|
||
#### Вариант C: Локальный запуск (без Docker)
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
export $(cat .env | xargs)
|
||
python zont_exporter.py
|
||
```
|
||
|
||
### 4. Проверка работы
|
||
|
||
```bash
|
||
# Логи
|
||
docker logs -f zont-exporter
|
||
|
||
# Метрики
|
||
curl http://localhost:8000/metrics
|
||
```
|
||
|
||
В ответе вы должны увидеть метрики вида:
|
||
|
||
```
|
||
# HELP zont_temperature_celsius Температура с датчиков ZONT
|
||
# TYPE zont_temperature_celsius gauge
|
||
zont_temperature_celsius{device_id="1580",device_name="Дом",sensor_name="Кухня"} 22.5
|
||
|
||
# HELP zont_boiler_working Работает ли котел (1 - да, 0 - нет)
|
||
# TYPE zont_boiler_working gauge
|
||
zont_boiler_working{device_id="1580",device_name="Дом"} 1
|
||
```
|
||
|
||
## 📊 Доступные метрики
|
||
|
||
| Метрика | Тип | Описание | Метки |
|
||
|---|---|---|---|
|
||
| `zont_temperature_celsius` | Gauge | Температура с датчиков | `device_id`, `device_name`, `sensor_name` |
|
||
| `zont_boiler_working` | Gauge | Работа котла за последнюю минуту (1/0) | `device_id`, `device_name` |
|
||
| `zont_signal_level` | Gauge | Уровень сигнала GSM или Wi-Fi | `device_id`, `device_name`, `type` |
|
||
| `zont_guard_state` | Gauge | Состояние охраны (1 — включена, 0 — выключена) | `device_id`, `device_name` |
|
||
|
||
## 🔗 Интеграция с Prometheus
|
||
|
||
Добавьте job в ваш `prometheus.yml`:
|
||
|
||
```yaml
|
||
scrape_configs:
|
||
- job_name: 'zont'
|
||
scrape_interval: 60s
|
||
static_configs:
|
||
- targets: ['zont-exporter:8000']
|
||
```
|
||
|
||
Если Prometheus запущен на хосте (вне Docker), используйте `host.docker.internal` или IP вашего сервера:
|
||
|
||
```yaml
|
||
scrape_configs:
|
||
- job_name: 'zont'
|
||
scrape_interval: 60s
|
||
static_configs:
|
||
- targets: ['host.docker.internal:8000']
|
||
```
|
||
|
||
## 📈 Полный стек мониторинга
|
||
|
||
Если у вас ещё нет Prometheus и Grafana, используйте готовый `docker-compose.yml`:
|
||
|
||
```yaml
|
||
services:
|
||
zont-exporter:
|
||
build: .
|
||
container_name: zont-exporter
|
||
restart: unless-stopped
|
||
env_file:
|
||
- .env
|
||
networks:
|
||
- monitoring
|
||
|
||
prometheus:
|
||
image: prom/prometheus:latest
|
||
container_name: prometheus
|
||
restart: unless-stopped
|
||
volumes:
|
||
- ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
|
||
- prometheus-data:/prometheus
|
||
ports:
|
||
- "9090:9090"
|
||
networks:
|
||
- monitoring
|
||
|
||
grafana:
|
||
image: grafana/grafana:latest
|
||
container_name: grafana
|
||
restart: unless-stopped
|
||
volumes:
|
||
- grafana-data:/var/lib/grafana
|
||
ports:
|
||
- "3000:3000"
|
||
networks:
|
||
- monitoring
|
||
|
||
networks:
|
||
monitoring:
|
||
driver: bridge
|
||
|
||
volumes:
|
||
prometheus-data:
|
||
grafana-data:
|
||
```
|
||
|
||
После запуска:
|
||
|
||
- **Prometheus**: http://localhost:9090
|
||
- **Grafana**: http://localhost:3000 (логин/пароль по умолчанию: `admin`/`admin`)
|
||
|
||
## ⚙️ Конфигурация
|
||
|
||
Все параметры задаются через переменные окружения:
|
||
|
||
| Переменная | Обязательна | По умолчанию | Описание |
|
||
|---|---|---|---|
|
||
| `ZONT_LOGIN` | ✅ | — | Логин от личного кабинета ZONT |
|
||
| `ZONT_PASSWORD` | ✅ | — | Пароль от личного кабинета ZONT |
|
||
| `ZONT_CLIENT_EMAIL` | ❌ | `exporter@localhost` | Контактный email (заголовок `X-ZONT-Client`) |
|
||
| `ZONT_API_URL` | ❌ | `https://my.zont.online/api` | Базовый URL API |
|
||
| `SCRAPE_INTERVAL` | ❌ | `60` | Интервал опроса в секундах |
|
||
| `EXPORTER_PORT` | ❌ | `8000` | Порт HTTP-сервера экспортера |
|
||
| `LOG_LEVEL` | ❌ | `INFO` | Уровень логирования (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |
|
||
|
||
## 🐳 Сборка Docker-образа
|
||
|
||
```bash
|
||
# Сборка
|
||
docker build -t zont-exporter:latest .
|
||
|
||
# Запуск с проверкой переменных
|
||
docker run --rm --env-file .env zont-exporter:latest
|
||
```
|
||
|
||
### Healthcheck
|
||
|
||
Docker автоматически проверяет доступность эндпоинта `/metrics` каждые 30 секунд. Если экспортер перестанет отвечать, контейнер будет помечен как `unhealthy`.
|
||
|
||
Проверить статус:
|
||
|
||
```bash
|
||
docker inspect --format='{{.State.Health.Status}}' zont-exporter
|
||
```
|
||
|
||
## 🔧 Расширение
|
||
|
||
### Добавление новых метрик
|
||
|
||
API ZONT предоставляет много данных. Чтобы добавить новую метрику, откройте `zont_exporter.py` и расширьте метод `collect()`:
|
||
|
||
```python
|
||
# Пример: сбор пользовательских статусов (custom_controls_state)
|
||
custom_gauge = GaugeMetricFamily(
|
||
'zont_custom_status',
|
||
'Пользовательский статус',
|
||
labels=['device_id', 'device_name', 'status_id']
|
||
)
|
||
|
||
for device in devices:
|
||
custom_state = device.get('io', {}).get('custom_controls_state', {})
|
||
for status_id, value in custom_state.items():
|
||
custom_gauge.add_metric(
|
||
[str(device['id']), device['name'], str(status_id)],
|
||
value
|
||
)
|
||
|
||
yield custom_gauge
|
||
```
|
||
|
||
### Полезные разделы API
|
||
|
||
Согласно [официальной документации](https://lk.zont-online.ru/api/docs/), для расширения доступны:
|
||
|
||
- `last-boiler-state` — детальное состояние котла (OpenTherm, модуляция, давление)
|
||
- `custom_controls_state` — пользовательские статусы (ZTC-7xx, Mega SX)
|
||
- `ztc_state` — состояние контроллера (баланс SIM, напряжение, статус-флаги)
|
||
- `temperature` — история температур через `load_data`
|
||
|
||
## 🐛 Отладка
|
||
|
||
### Экспортер не запускается
|
||
|
||
Проверьте логи:
|
||
|
||
```bash
|
||
docker logs zont-exporter
|
||
```
|
||
|
||
Частые причины:
|
||
|
||
- Не заданы `ZONT_LOGIN` или `ZONT_PASSWORD`
|
||
- Неверный логин/пароль
|
||
- Отсутствует доступ к `my.zont.online`
|
||
|
||
### Метрики пустые
|
||
|
||
- Убедитесь, что к вашему аккаунту ZONT привязаны устройства.
|
||
- Проверьте `ZONT_CLIENT_EMAIL` — некоторые методы требуют корректного контакта.
|
||
- Увеличьте `LOG_LEVEL=DEBUG` для детальной диагностики.
|
||
|
||
### Проблемы с токеном
|
||
|
||
Экспортер автоматически обновляет токен при получении `403`. Если проблема повторяется:
|
||
|
||
- Убедитесь, что пароль не содержит спецсимволов, требующих экранирования.
|
||
- Проверьте, не отозван ли токен в личном кабинете ZONT.
|
||
|
||
## 📚 Документация API ZONT
|
||
|
||
- Официальная документация: https://lk.zont-online.ru/api/docs/
|
||
- Облегчённое Widget API v3: https://my.zont.online/api/widget/v3
|
||
- Сайт производителя: https://zont.online
|
||
|
||
## 📄 Лицензия
|
||
|
||
MIT
|
||
|
||
## 🤝 Вклад
|
||
|
||
Pull request'ы приветствуются. Для крупных изменений сначала откройте issue для обсуждения.
|
||
|
||
---
|
||
|
||
**Полезные ссылки:**
|
||
|
||
- [Prometheus](https://prometheus.io/)
|
||
- [Grafana](https://grafana.com/)
|
||
- [prometheus-client (Python)](https://github.com/prometheus/client_python) |