monlet/README.ru.md

English | Русский

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:

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:

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
2. agent/README.md
3. server/README.md
4. web/README.md
5. api/README.md
6. CONFIG_REFERENCE.ru.md (English)
7. 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.