155 lines
6.2 KiB
Markdown
155 lines
6.2 KiB
Markdown
[English](README.md) | Русский
|
||
|
||
# Monlet
|
||
|
||
Monlet 0.1.0 - небольшой self-hosted мониторинг для локальных проверок,
|
||
heartbeat-состояния хостов, инцидентов и доставки уведомлений.
|
||
|
||
|
||
|
||
Monlet закрывает промежуток между набором shell-проверок и полноценной
|
||
observability-платформой. Агенты запускают проверки там, где живут факты,
|
||
отправляют на сервер только структурированные наблюдения, а жизненный цикл
|
||
инцидентов и уведомлений остаётся в одном центральном backend.
|
||
|
||
## Зачем Monlet?
|
||
|
||
Простая инфраструктура часто начинается с cron-задач, shell-проб и webhook в
|
||
чат. Это работает, пока не нужно быстро ответить на базовые операционные
|
||
вопросы:
|
||
|
||
- какие хосты alive, stale или dead;
|
||
- какие локальные проверки сейчас degraded;
|
||
- открылся ли инцидент, закрылся ли он или событие было deduplicated;
|
||
- ушло ли уведомление, попало ли в retry или failed;
|
||
- переживут ли агенты outage сервера без дублей событий.
|
||
|
||
Monlet делает эту модель явной, но не добавляет remote command execution,
|
||
remote config push или тяжёлую incident-management платформу.
|
||
|
||
## Что он делает
|
||
|
||
- Go agent запускает локальные команды из TOML-конфига.
|
||
- Агенты отправляют heartbeats и check events на сервер через `/api/v1`.
|
||
- FastAPI server владеет inventory, текущим состоянием checks, incidents,
|
||
retention и retry для notifier outbox.
|
||
- Next.js UI показывает agents, checks, incidents, events и delivery state
|
||
уведомлений.
|
||
- Новый agent key должен пройти operator admission, прежде чем сможет влиять на
|
||
monitoring state.
|
||
- Server и agents экспортируют Prometheus metrics для самого Monlet.
|
||
|
||
## Скриншоты
|
||
|
||
Agents и admission state:
|
||
|
||
|
||
|
||
Текущие check states:
|
||
|
||
|
||
|
||
Open и resolved incidents:
|
||
|
||
|
||
|
||
Состояние notifier outbox:
|
||
|
||
|
||
|
||
## Возможности в 0.1.0
|
||
|
||
- Локальные command checks со статусами `ok`, `warning`, `critical` и `unknown`.
|
||
- Timeout для каждой проверки и best-effort resource limits для scripts: CPU
|
||
time, virtual memory и open files.
|
||
- Agent liveness по heartbeat: alive, stale и dead.
|
||
- Durable on-disk spool в агенте на случай outage сервера.
|
||
- Idempotent event ingestion и replay без дублей.
|
||
- Server-owned lifecycle для открытия и закрытия incidents.
|
||
- Notification outbox со статусами retry и failure.
|
||
- Debug, webhook, Telegram и Alertmanager notifier implementations.
|
||
- Agent admission и blacklist controls.
|
||
- Partitioned PostgreSQL event storage и bounded retention.
|
||
- Docker Compose local stack и showcase stand.
|
||
- Prometheus metrics для server и agent runtime behavior.
|
||
|
||
## Быстрый старт
|
||
|
||
Запустить локальный stack:
|
||
|
||
```sh
|
||
cd deploy
|
||
MONLET_AUTH_TOKEN=$(openssl rand -hex 16) docker compose up --build
|
||
```
|
||
|
||
Сервисы:
|
||
|
||
- Web UI: <http://127.0.0.1:3000>
|
||
- Server API: <http://127.0.0.1:8000>
|
||
- Readiness: <http://127.0.0.1:8000/api/v1/ready>
|
||
- Metrics: <http://127.0.0.1:8000/metrics>
|
||
|
||
Запустить полный demo stand:
|
||
|
||
```sh
|
||
SHOWCASE_KEEP=1 bash deploy/e2e-showcase.sh
|
||
```
|
||
|
||
Showcase поднимает PostgreSQL, server, web UI, mock webhook и несколько demo
|
||
agents. Он прогоняет mixed check states, liveness transitions, resolved
|
||
incidents, notifier retries/failures и spool replay.
|
||
|
||
## Архитектура
|
||
|
||
Monlet - monorepo с тремя независимыми приложениями:
|
||
|
||
- `agent/` - Go binary для monitored hosts.
|
||
- `server/` - Python/FastAPI backend с PostgreSQL storage.
|
||
- `web/` - Next.js operator dashboard.
|
||
|
||
Server владеет lifecycle инцидентов и уведомлений. Agent отправляет только
|
||
факты. Web UI read-only для monitoring state; agent admission и blacklist
|
||
controls - mutation surface для v1.
|
||
|
||
Публичный API contract лежит в `api/openapi.yaml`. Design и operations docs
|
||
начинаются с `docs/index.md`.
|
||
|
||
## Не цели
|
||
|
||
Monlet 0.1.0 намеренно не является:
|
||
|
||
- remote command runner;
|
||
- системой remote config push;
|
||
- заменой Grafana;
|
||
- полноценной incident-management платформой;
|
||
- multi-tenant RBAC продуктом;
|
||
- Kubernetes operator;
|
||
- distributed server cluster.
|
||
|
||
## Разработка
|
||
|
||
Начинать отсюда:
|
||
|
||
1. [deploy/README.md](deploy/README.md)
|
||
2. [agent/README.md](agent/README.md)
|
||
3. [server/README.md](server/README.md)
|
||
4. [web/README.md](web/README.md)
|
||
5. [api/README.md](api/README.md)
|
||
6. [CONFIG_REFERENCE.ru.md](CONFIG_REFERENCE.ru.md) ([English](CONFIG_REFERENCE.md))
|
||
7. [docs/index.md](docs/index.md)
|
||
|
||
Dependency caches и virtual environments хранятся внутри репозитория. Актуальные
|
||
команды local development описаны в component README.
|
||
|
||
## Статус
|
||
|
||
Monlet - активный early-stage проект. Release 0.1.0 пригоден для local
|
||
development, demos и controlled internal deployments. Internal contracts ещё
|
||
могут меняться, при этом public API остаётся versioned under `/api/v1`.
|
||
|
||
`0.1.0` - версия product release. `/api/v1` - namespace API.
|
||
|
||
## Лицензия
|
||
|
||
MIT.
|