# 14 — İzleme ve Sağlık (Monitoring & Health)

> Kısa özet: 17 metrik + Prometheus/Node Exporter/Grafana OSS + Uptime Kuma + `bf-status`/`bf-diagnostics`/`bf-support-bundle` sözleşmeleri. Monitoring operatörü ve saha teknisyeni içindir.
>
> - Dosya: `docs/14-MONITORING-AND-HEALTH.md`
> - İlgili kararlar: `24-DECISION-LOG.md#K-07`, `#K-14`
> - Durum: [ ] Taslak

---

## 1. Amaç

700 cihazda "hangisi ölü, hangisi hasta, hangisi sağlıklı" sorusuna iki perdede cevap: mühendis için metrik (Prometheus), teknisyen için UP/DOWN + last-seen (Uptime Kuma).

## 2. Kapsam

- Kapsam içi: 17 metrik listesi, Prometheus/Node Exporter/Grafana OSS/Uptime Kuma rolleri, scrape/retention ilkeleri, 3 saha komutu sözleşmesi.
- Kapsam dışı: log içerik politikası (15), alarm bildirim hedefleri detayı (kurulum dokümanına havale), merkez donanım siparişi.

## 3. Kararlar

```text
KARAR:    Birincil metrik yığını Prometheus + Node Exporter + Grafana OSS'tir; 17 metriğin tamamı burada toplanır.
GEREKÇE:  17 metriğin tamamı yalnızca bu yığında ücretsiz ve kotasız toplanır (WireGuard/Docker/MEG sağlığı textfile collector ile).
ALTERNATİF: Netdata Cloud — Free 5 node kotası 700 cihazda ücrete düşer, elendi. Yalnızca Kuma — metrik körlüğü, elendi.
RİSK:     700 node kardinalite/saklama yükü; azaltma: 60 sn scrape, 30–90 gün retention, `BF-<no>` etiket şeması.
MALİYET:  Ücretsiz.
LİSANS:   Prometheus/Node Exporter Apache-2.0 — https://github.com/prometheus/prometheus + https://prometheus.io/docs/guides/node-exporter/ (2026-09-15); Grafana OSS AGPL-3.0 — https://grafana.com/oss/ (2026-09-15).
```

```text
KARAR:    Tamamlayıcı olarak Uptime Kuma: saha-teknisyeni dostu UP/DOWN panosu + Push "last seen" + bildirimler.
GEREKÇE:  Metrik bilmeyen teknisyene en basit çevrimdışı alarmını verir (20 sn aralık, 90+ bildirim servisi, tek konteyner).
ALTERNATİF: Yalnızca Grafana alarmı — teknisyen için karmaşık, elendi.
RİSK:     Kuma metrik vermez; azaltma: Prometheus ile birlikte koşar, rol çakışması yok.
MALİYET:  Ücretsiz.
LİSANS:   Uptime Kuma MIT — https://github.com/louislam/uptime-kuma (2026-09-15).
```

```text
KARAR:    Özel metrikler (WireGuard handshake, Docker, MEG) Node Exporter textfile collector `.prom` dosyalarıyla verilir.
GEREKÇE:  Standart Prometheus yolu; özel exporter yazma yükü yok.
ALTERNATİF: Özel exporter geliştirme — bakım yükü, elendi.
RİSK:     `.prom` yazım hatası scrape'i bozar; azaltma: cron/systemd timer çıktısı atomik yazılır.
MALİYET:  Ücretsiz.
LİSANS:   Node Exporter Apache-2.0 — https://github.com/prometheus/node_exporter (2026-09-15).
```

```text
KARAR:    Saha sağlık sözleşmeleri: `bf-status` (hızlı bakış), `bf-diagnostics` (derin tanı), `bf-support-bundle` (secret sızdırmaz paket).
GEREKÇE:  700 dokunulmaz cihazda logsuz metrik kör, metriksiz log sağırdır; bundle secret dışlama kuralıyla güvenli uzaktan tanı sağlar.
ALTERNATİF: Harici log platformu (Loki/ELK) ilk fazda — ek servis yükü, elendi (Faz-sonrası hedef).
RİSK:     Bundle'a secret kaçması; azaltma: dışlama listesi + üreticide maskeleme testi.
MALİYET:  Ücretsiz.
LİSANS:   systemd-journald / textfile (Apache-2.0) — https://github.com/prometheus/node_exporter (2026-09-15).
```

## 4. Neden Bu Karar?

İki kullanıcı, iki hız: mühendis kök nedeni metrikten bulur, teknisyen kesintiyi Kuma'dan görür. Scrape 60 sn + retention 30–90 gün, 700 node'da merkez yükünü taşınabilir tutar.

## 5. Alternatifler

| Alternatif | Artı | Eksi | Sonuç |
|---|---|---|---|
| Yalnızca Uptime Kuma | Çok kolay | Metrik körlüğü | Elendi |
| Netdata Cloud | Zengin agent | Free 5 node kotası | Elendi |
| Netdata Parent self-hosted | Zengin | Merkezi tasarım yükü + kota riski | Elendi |
| Loki/ELK ilk fazda | Güçlü log | Ek servis yükü, sadelik ihlali | Faz-sonrasına ertelendi |

## 6. Avantajlar

- Tamamı ücretsiz ve kotasız; 700 cihaz lisans duvarına çarpmaz.
- Tek kimlik (`BF-<no>`) metrikten loga join anahtarıdır.

## 7. Dezavantajlar

- Prometheus 700 node işletme bilgisi ister; retention LAB ölçümü olmadan donanım siparişi verilmemeli.
- Kuma + Prometheus çift kurulum merkezde iki servis demektir.

## 8. Riskler

| Risk | Olasılık | Etki | Azaltma |
|---|---|---|---|
| Kardinalite patlaması | Orta | Orta | 60 sn scrape, etiket disiplini, federasyon hedefi |
| Retention şişmesi | Orta | Orta | 30–90 gün, PİLOT hacim ölçümü |
| Bundle secret sızıntısı | Düşük | Yüksek | Dışlama listesi + maskeleme testi |

## 9. Uygulama Planı

1. Merkez: Prometheus + Grafana OSS + Uptime Kuma kurulur.
2. Saha: Node Exporter + textfile cron/timer + Kuma Push kurulur.
3. Etiket şeması `device_id="BF-<no>"` tüm metriklerde uygulanır.
4. `bf-status` / `bf-diagnostics` / `bf-support-bundle` sahaya dağıtılır.

```bash
# saha: Node Exporter + textfile dizini (örnek)
systemctl enable --now node_exporter
ls /var/lib/node_exporter/textfile/  # *.prom buraya atomik yazılır

# WireGuard handshake örneği (üretici script özeti)
# wg show wg0 latest-handshakes > /var/lib/node_exporter/textfile/wireguard.prom.tmp \
#   && mv .../wireguard.prom.tmp .../wireguard.prom
```

### 17 metrik listesi

| # | Metrik | Kaynak | Ne için |
|---|---|---|---|
| 1 | `up` | Prometheus scrape | Cihaz scrape edilebilir mi (ölü/diri) |
| 2 | `node_cpu_seconds_total` | Node Exporter | CPU yükü |
| 3 | `node_memory_MemAvailable_bytes` | Node Exporter | RAM baskısı |
| 4 | `node_filesystem_avail_bytes` | Node Exporter | Disk dolumu |
| 5 | `node_load1/5/15` | Node Exporter | Yük ortalaması |
| 6 | `node_network_receive/transmit_bytes_total` | Node Exporter | Ağ trafiği |
| 7 | `node_systemd_unit_state` | Node Exporter (systemd) | Kritik servis ayakta mı |
| 8 | `node_timex_offset_seconds` | Node Exporter | Saat kayması (TLS/WG için kritik) |
| 9 | `node_boot_time_seconds` | Node Exporter | Beklenmedik reboot tespiti |
| 10 | `wireguard_last_handshake_seconds` | textfile | Tünel canlılığı (stale = kopuk) |
| 11 | `wireguard_transfer_bytes` | textfile | Tünel trafiği |
| 12 | `docker_container_running` | textfile | MEG/yan konteyner ayakta mı |
| 13 | `docker_container_restart_count` | textfile | Crash-loop tespiti |
| 14 | `meg_up` | textfile | MEG sağlığı (kabul madde 6 ile aynı kaynaktan) |
| 15 | `meg_last_success_timestamp` | textfile | MEG iş yapıyor mu (stale = takılı) |
| 16 | `unattended_upgrade_active` | textfile | K-11 kilidi delinmiş mi (1 = ihlal) |
| 17 | `kuma_push_last_seen` | Uptime Kuma Push | Teknisyen "last seen" görünümü |

Scrape: 60 sn. Retention: 30–90 gün (LAB ölçümüyle kesinleşir).

## 10. Test Planı

| Test | Beklenen sonuç | Ortam |
|---|---|---|
| Scrape + 17 metrik | Grafana panosu dolu | P1(5) |
| WG down simülasyonu | Metrik 10 stale + Kuma DOWN | P1(5) |
| Konteyner kill | Metrik 12/13 alarm | LAB(2) |
| `unattended-upgrade` açma | Metrik 16 = 1 alarm | LAB(2) |
| Kuma Push kesintisi | last-seen bayatlar | P1(5) |

## 11. Rollback

1. Bozuk exporter/push, önceki sürüme Ansible ile geri alınır.
2. Prometheus config hatasında önceki config + `promtool check config` ile dönüş.
3. Son çare: monitoring'siz işletim (erişim kanalları bağımsızdır — 01).

## 12. Kontrol Listesi

- [ ] 17 metriğin tamamı Grafana'da görünüyor.
- [ ] Kuma UP/DOWN + Push last-seen çalışıyor.
- [ ] Etiket şeması `BF-<no>` tutarlı.
- [ ] Scrape 60 sn, retention 30–90 gün aralığında.

### `bf-status` örnek çıktısı (16 satır sözleşmesi)

```text
BF-12010193  2026-09-15 12:00 +03  OK
uptime: 6d 4h 12m | load: 0.31 0.28 0.22
cpu: 8% | mem: 1.1/3.8G (29%) | disk /: 9.2/28G (33%)
net: wg0 UP, handshake 12s ago | rx 41M tx 18M
docker: daemon UP | meg:1.2.3 running 6d (restarts 0)
meg: UP, last success 40s ago
systemd: docker OK | wg-quick@wg0 OK | xrdp OFF | node_exporter OK
unattended-upgrades: DISABLED (timer masked)
ufw: active, default DENY in | 22/3389 wg0-only
gui: OFF (multi-user) | rdp sessions: 0
kuma push: OK 30s ago | prometheus scrape: OK 45s ago
rustdesk: online | meshcentral: online
boot: 2026-09-09 07:48 (power-loss recovery OK)
alerts: 0 critical, 1 warning (disk trend)
next: support bundle: bf-support-bundle
```

`bf-diagnostics`: yukarıdakinin detaylı sürümü (servis log kuyrukları + `ss` + `df -i` + textfile içerikleri). `bf-support-bundle`: aynı paketin tarball'ı; WireGuard private key, RustDesk şifresi, SSH private key ve `authorized_keys` dışı secret'lar ASLA pakete girmez (üretici maskeleme testinden geçer).

## 13. Açık Sorular

- [ ] Prometheus retention/kardinalite hesabı (700 × 60 sn) — LAB ölçümü (sahibi: 14 yazarı).
- [ ] Bildirim hedefleri (SMS/e-posta/webhook) — merkez kurulumunda netleşecek (sahibi: Faz 3).
- [ ] Federasyon gerekip gerekmediği — 700 node ölçümü (sahibi: 14 yazarı).

---

## Ek: Mermaid — Metrik akışı

```mermaid
flowchart LR
    SAHA["Saha bf-<no><br/>Node Exporter + textfile"] -->|scrape 60sn| PROM["Prometheus"]
    PROM --> GRAF["Grafana OSS"]
    SAHA -->|Push last-seen| KUMA["Uptime Kuma"]
    KUMA --> TECH["Teknisyen panosu"]
    GRAF --> ENG["Mühendis panosu"]
    SAHA -->|bf-status| CONSOLE["Saha konsolu"]
```