ZONT Prometheus Exporter

Экспортер метрик для устройств ZONT и Mega SX в формате, совместимом с Prometheus. Позволяет собирать данные о температуре, состоянии котла, уровне сигнала, охране и других параметрах через официальный API ZONT.

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

• 🔐 Аутентификация через официальный API ZONT (my.zont.online/api)
• 🌡️ Сбор температуры с проводных и радиодатчиков
• 🔥 Мониторинг работы котла (время работы, аварии)
• 📶 Уровень сигнала GSM/Wi-Fi
• 🛡️ Состояние охраны и сирены
• 🚗 Данные об автомобиле (ZTC): зажигание, двигатель, автозапуск
• 🐳 Готов к запуску в Docker
• ⚙️ Полностью настраивается через переменные окружения
• 🩺 Встроенный healthcheck

🚀 Быстрый старт

1. Клонирование проекта

git clone <ваш-репозиторий>/zont-exporter.git
cd zont-exporter

2. Настройка окружения

Создайте файл .env на основе примера и заполните своими данными:

cp .env.example .env
nano .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 (рекомендуется)

docker compose up -d --build

Вариант B: Docker build + run

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)

pip install -r requirements.txt
export $(cat .env | xargs)
python zont_exporter.py

4. Проверка работы

# Логи
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:

scrape_configs:
  - job_name: 'zont'
    scrape_interval: 60s
    static_configs:
      - targets: ['zont-exporter:8000']

Если Prometheus запущен на хосте (вне Docker), используйте host.docker.internal или IP вашего сервера:

scrape_configs:
  - job_name: 'zont'
    scrape_interval: 60s
    static_configs:
      - targets: ['host.docker.internal:8000']

📈 Полный стек мониторинга

Если у вас ещё нет Prometheus и Grafana, используйте готовый docker-compose.yml:

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-образа

# Сборка
docker build -t zont-exporter:latest .

# Запуск с проверкой переменных
docker run --rm --env-file .env zont-exporter:latest

Healthcheck

Docker автоматически проверяет доступность эндпоинта /metrics каждые 30 секунд. Если экспортер перестанет отвечать, контейнер будет помечен как unhealthy.

Проверить статус:

docker inspect --format='{{.State.Health.Status}}' zont-exporter

🔧 Расширение

Добавление новых метрик

API ZONT предоставляет много данных. Чтобы добавить новую метрику, откройте zont_exporter.py и расширьте метод collect():

# Пример: сбор пользовательских статусов (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

Согласно официальной документации, для расширения доступны:

• last-boiler-state — детальное состояние котла (OpenTherm, модуляция, давление)
• custom_controls_state — пользовательские статусы (ZTC-7xx, Mega SX)
• ztc_state — состояние контроллера (баланс SIM, напряжение, статус-флаги)
• temperature — история температур через load_data

🐛 Отладка

Экспортер не запускается

Проверьте логи:

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
• Grafana
• prometheus-client (Python)