# 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)