homelab-docs/docs/monitoring/dashboard-plan.md

План реализации дашборда мониторинга 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 — установка и алерты
• smartd-setup.md — SMART дисков
• container-100 — NPM, log-dashboard
• architecture — обзор контейнеров