Add readme.md
This commit is contained in:
energys
@@ -0,0 +1,299 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user