Files
buryan-infra/ops/monitoring/CHECKS-HOWTO.md
T

113 lines
4.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Проверки по смыслу
## Что это
**Было:** проверяем «порт открыт».
**Стало:** проверяем «служба РАБОТАЕТ».
Разница важная: служба может отвечать кодом 200, но при этом
не работать с базой, отдавать заглушку или страницу ошибки.
## Как проверяем
| Способ | Что проверяет |
|---|---|
| **Содержимое ответа** | отдаёт ли служба ОЖИДАЕМЫЙ ответ |
| **Работа с базой** | реальный SQL-запрос к каждой базе |
| **Через домены** | работает ли вход так, как видит пользователь |
| **Не 5xx** | служба не отдаёт ошибку сервера |
## Примеры проверок
```
Gitea → /api/v1/version должен вернуть "version"
Vaultwarden → /alive должен ответить
Matrix → /_matrix/client/versions должен вернуть "versions"
Element → должен вернуть "Buryan" (наш бренд)
Immich → /api/server/ping должен вернуть "pong"
Grafana → /api/health должен вернуть "ok"
Prometheus → /-/healthy должен вернуть "Healthy"
Loki → /ready должен вернуть "ready"
Базы (реальные запросы):
gitea_db → количество репозиториев
matrix_db → количество пользователей
vaultwarden_db → количество пользователей
```
## Расписание
```
каждые 5 минут: /opt/buryan-hub/scripts/check-services.sh
журнал: /var/log/buryan-hub/checks.log
состояние: /var/lib/buryan-checks/last-fail
```
## Умная тревога
**Тревога отправляется ТОЛЬКО при НОВОМ провале.**
Если та же проблема повторяется — не заваливает повторами.
**При восстановлении** приходит сообщение «всё восстановилось»
с перечнем того, что сбоило.
## Проверить вручную
```bash
/opt/buryan-hub/scripts/check-services.sh
tail -20 /var/log/buryan-hub/checks.log
cat /var/lib/buryan-checks/last-fail
```
## Что это даёт
О поломке узнаём **до пользователя** — и узнаём, что именно
сломалось, а не просто «что-то не отвечает».
---
## Исправление ложных проверок (16.10.2026)
### Что было не так
Первый запуск дал два **ложных** провала:
| Провал | Почему ложный |
|---|---|
| `PostgreSQL: не отвечает` | PostgreSQL **не говорит по HTTP** — я проверял базу как сайт |
| `Element: нет 'Buryan'` | Element — приложение на JavaScript, слова нет в начальном HTML |
**Обе службы были исправны.** Ошибалась проверка.
### Как исправлено
```
PostgreSQL → убрана HTTP-проверка, оставлен РЕАЛЬНЫЙ запрос к базе
Element → проверяется /config.json (там есть наш бренд «Buryan»)
Alertmanager→ убран путь /-/healthy (у него другой), проверяется корень
```
### Урок
**Это повторение того же правила:** при расхождении — сначала
проверить саму проверку, а не службу.
Признак хорошей проверки: она опирается на **документированный
адрес состояния** (`/health`, `/ping`, `/ready`, `/api/health`),
а не на догадку о содержимом страницы.
### Таблица адресов состояния
| Служба | Адрес для проверки |
|---|---|
| Gitea | `/api/v1/version` |
| Matrix | `/_matrix/client/versions` |
| Vaultwarden | `/alive` |
| Immich | `/api/server/ping` |
| Grafana | `/api/health` |
| Prometheus | `/-/healthy` |
| Loki | `/ready` |
| Syncthing | `/rest/noauth/health` |
| Sonarr/Radarr/Prowlarr | `/ping` |
| Element | `/config.json` (там бренд) |