# План реализации дашборда мониторинга homelab

Дашборд для Netdata (http://192.168.1.150:19999) с блоками: хост, контейнеры, критические сервисы.

---

## Текущее состояние (по результатам проверки на сервере)

### Netdata
- **Версия:** v2.9.0
- **Режим:** локальный, Cloud отключён
- **API:** http://localhost:19999/api/v1/ — доступен

### Доступные метрики

| Блок | Метрика | Chart / источник | Статус |
|------|---------|------------------|--------|
| **Хост** | CPU total | `system.cpu` (user, system, nice, iowait, …) | ✅ |
| | RAM total | `system.ram` | ✅ |
| | Disk usage | `disk_space./`, `disk_space./mnt/backup`, `disk_space./mnt/nextcloud-hdd`, `disk_space./tank`, … (в API: URL-encode слэши) | ✅ |
| | iowait | `system.cpu` dimension `iowait` | ✅ |
| | load | `system.load` (load1, load5, load15) | ✅ |
| **Контейнеры** | CPU % | `cgroup_<name>.cpu_limit` (used) | ✅ |
| | RAM % | `cgroup_<name>.mem_utilization` | ✅ |
| | Disk % | скрипт `pct exec ID -- df -P /` | ✅ кастомный экспортер |
| | OOM count | `/sys/fs/cgroup/lxc/ID/memory.events` (oom_kill) | ✅ кастомный экспортер |
| **Сервисы** | Immich, Nextcloud, nginx, VPN | ссылки на charts Netdata | ✅ без response time/connections |

### Контейнеры в cgroups (по данным Netdata)
- `nginx` (CT 100)
- `nextcloud` (CT 101)
- `gitea` (CT 103)
- `paperless` (CT 104)
- `rag-service` (CT 105)
- `misc` (CT 107, Invidious)
- `galene` (CT 108)
- `local-vpn` (CT 109)
- `qemu_immich` (VM 200)

---

## Решения (по ответам пользователя)

1. **Disk % по контейнерам** — в приоритете. I/O не нужен. Реализация: скрипт на хосте, `pct exec ID -- df -P /` для каждого LXC, VM 200 — отдельно (`qm guest exec` или аналог).
2. **OOM** — `cgroup memory.events` (oom_kill) по каждому контейнеру. Путь: `/sys/fs/cgroup/lxc/ID/memory.events` (LXC), для VM — cgroup QEMU.
3. **Response time / open connections** — отложено, не требуется.
4. **Размещение** — на хосте (192.168.1.150).
5. **Netdata Cloud** — не рассматривается.

---

## Варианты реализации дашборда

### Вариант A: Netdata Cloud — не используется (Cloud отключён)

### Вариант B: Кастомная HTML-страница (выбран)
- Страница на хосте (192.168.1.150), которая:
  - запрашивает Netdata API (`/api/v1/data?chart=...`)
  - рендерит блоки: хост, таблица контейнеров, сервисы
- Плюсы: полный контроль, работает без Cloud
- Минусы: нужна разработка и хостинг страницы

### Вариант C: Доработка стандартного дашборда Netdata
- `dashboard_info.js` — изменение порядка/группировки charts
- Плюсы: используем встроенный UI
- Минусы: ограниченная кастомизация, в v2 подход мог измениться

---

## Рекомендуемый план (поэтапно)

### Этап 1: Дашборд на базе Netdata API (Вариант B)
Создать кастомную HTML-страницу с тремя блоками.

**Блок 1 — Хост**
- CPU total: `system.cpu` (сумма user+system или 100-idle)
- RAM total: `system.ram` (used, cached, free)
- Disk usage: `disk_space./`, `disk_space./mnt/backup`, `disk_space./mnt/nextcloud-hdd`, `disk_space./tank` (avail/used %)
- iowait: `system.cpu` dimension iowait
- load: `system.load` (load15)

**Блок 2 — Контейнеры (таблица)**
- Колонки: имя, CPU %, RAM %, Disk %, OOM count
- CPU/RAM: `cgroup_<name>.cpu_limit`, `cgroup_<name>.mem_utilization` (Netdata API)
- Disk %: кастомный API (скрипт `pct exec ID -- df -P /` + парсинг)
- OOM: кастомный API (LXC: `/sys/fs/cgroup/lxc/ID/memory.events`, VM 200: `/sys/fs/cgroup/qemu.slice/200.scope/memory.events` → oom_kill)

**Блок 3 — Критические сервисы**
- Immich, Nextcloud, nginx, VPN — ссылки на charts Netdata (cgroup_*, app.nginx_*)
- Response time / open connections — не требуются

### Этап 2: Кастомный экспортер (скрипт + HTTP API)
Скрипт на хосте, запускаемый по таймеру или по запросу:
- **Disk %:** для каждого LXC (100–109) — `pct exec ID -- df -P /`; для VM 200 — `qm guest exec` или fallback (lvs/zfs)
- **OOM:** чтение `oom_kill` из `/sys/fs/cgroup/lxc/ID/memory.events` (LXC), `/sys/fs/cgroup/qemu.slice/200.scope/memory.events` (VM 200)
- Отдача JSON на HTTP (например, порт 19998 или через nginx на хосте)

### Этап 3: Размещение и интеграция
- Дашборд: статика на хосте (nginx или python -m http.server), запросы к Netdata API (localhost:19999) и кастомному API
- Добавить ссылку в Homepage (services.yaml)

---

## VM 200 (Immich) — RAM после увеличения

При увеличении RAM с 6 до 10 GB «потребление» может визуально «упасть» по нескольким причинам:

1. **Процент vs абсолютное значение** — 32% от 10 GB ≈ 3.2 GB. Та же нагрузка при 6 GB давала бы ~53%. Дашборд показывает RAM % (cgroup mem_utilization).
2. **Сброс кэша** — при нехватке памяти гость держит кэш; после добавления RAM ядро может освободить кэш, и «used» уменьшается.
3. **Balloon** — virtio-balloon мог забирать память при 6 GB; после увеличения лимита balloon отдаёт память гостю, но реальное использование приложений может остаться ~3 GB.

**Проверка:** `qm guest exec 200 -- free -h` (требует qemu-guest-agent в гостевой ОС) — смотреть `Mem: used` внутри гостя.

---

## Реализовано (2026-02-28)

- **URL дашборда:** http://192.168.1.150:19998
- **Ссылка в Homepage:** добавлена (Сервисы → Homelab Dashboard)
- **Скрипты:** `scripts/dashboard/` (exporter, server, index.html, deploy, add-to-homepage)
- **Systemd:** `homelab-dashboard.service` (порт 19998)

---

## Маппинг CT/VM → cgroup name (Netdata)

| ID | Назначение | cgroup name |
|----|------------|-------------|
| 100 | nginx | cgroup_nginx |
| 101 | nextcloud | cgroup_nextcloud |
| 103 | gitea | cgroup_gitea |
| 104 | paperless | cgroup_paperless |
| 105 | rag-service | cgroup_rag-service |
| 107 | misc (Invidious) | cgroup_misc |
| 108 | galene | cgroup_galene |
| 109 | local-vpn | cgroup_local-vpn |
| 200 | immich (VM) | cgroup_qemu_immich |

---

## Связанные документы

- [netdata-proxmox-setup.md](netdata-proxmox-setup.md) — установка и алерты
- [smartd-setup.md](smartd-setup.md) — SMART дисков
- [container-100](../containers/container-100.md) — NPM, log-dashboard
- [architecture](../architecture/architecture.md) — обзор контейнеров