154 lines
4.8 KiB
Markdown
154 lines
4.8 KiB
Markdown
English | [Русский](README.ru.md)
|
|
|
|
# Monlet
|
|
|
|
Monlet 0.1.0 is a small self-hosted monitoring system for local checks, host
|
|
heartbeats, incidents, and notification delivery state.
|
|
|
|
|
|
|
|
Monlet is built for the gap between ad-hoc shell checks and a full observability
|
|
platform. Agents run checks on the hosts where the facts live, push only
|
|
structured observations to the server, and leave incident and notification
|
|
lifecycle decisions to one central backend.
|
|
|
|
## Why Monlet?
|
|
|
|
Simple infrastructure often starts with cron jobs, shell probes, and a chat
|
|
webhook. That works until you need to answer basic operational questions:
|
|
|
|
- Which hosts are alive, stale, or dead?
|
|
- Which local checks are currently degraded?
|
|
- Did this failure open an incident, resolve one, or get deduplicated?
|
|
- Were notifications sent, retried, or failed?
|
|
- Can agents survive a server outage without creating duplicate events?
|
|
|
|
Monlet keeps that model explicit without adding remote command execution,
|
|
remote config push, or a heavyweight incident-management platform.
|
|
|
|
## What It Does
|
|
|
|
- A Go agent runs configured local commands from TOML.
|
|
- Agents send heartbeats and check events to the server over the `/api/v1` API.
|
|
- The FastAPI server owns inventory, current check state, incidents, retention,
|
|
and notifier outbox retries.
|
|
- The Next.js UI shows agents, checks, incidents, events, and notification
|
|
delivery state.
|
|
- Operator admission is required before a new agent key can affect monitoring
|
|
state.
|
|
- Server and agents expose Prometheus metrics for the monitoring system itself.
|
|
|
|
## Screenshots
|
|
|
|
Agents and admission state:
|
|
|
|
|
|
|
|
Current check states:
|
|
|
|
|
|
|
|
Open and resolved incidents:
|
|
|
|
|
|
|
|
Notifier outbox state:
|
|
|
|
|
|
|
|
## Features in 0.1.0
|
|
|
|
- Local command checks with `ok`, `warning`, `critical`, and `unknown` states.
|
|
- Per-check timeouts and best-effort script resource limits for CPU time,
|
|
virtual memory, and open files.
|
|
- Heartbeat-based agent liveness with alive, stale, and dead status.
|
|
- Durable on-disk agent spool for server outages.
|
|
- Idempotent event ingestion and duplicate-safe replay.
|
|
- Server-owned incident open/resolve lifecycle.
|
|
- Notification outbox with retry and failure state.
|
|
- Debug, webhook, Telegram, and Alertmanager notifier implementations.
|
|
- Agent admission and blacklist controls.
|
|
- Partitioned PostgreSQL event storage and bounded retention.
|
|
- Docker Compose local stack and showcase stand.
|
|
- Prometheus metrics for server and agent runtime behavior.
|
|
|
|
## Quick Start
|
|
|
|
Run the local stack:
|
|
|
|
```sh
|
|
cd deploy
|
|
MONLET_AUTH_TOKEN=$(openssl rand -hex 16) docker compose up --build
|
|
```
|
|
|
|
Services:
|
|
|
|
- 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>
|
|
|
|
Run the full demo stand:
|
|
|
|
```sh
|
|
SHOWCASE_KEEP=1 bash deploy/e2e-showcase.sh
|
|
```
|
|
|
|
The showcase starts PostgreSQL, the server, the web UI, a mock webhook, and
|
|
several demo agents. It drives mixed check states, liveness transitions,
|
|
resolved incidents, notifier retries/failures, and spool replay.
|
|
|
|
## Architecture
|
|
|
|
Monlet is a monorepo with three independent applications:
|
|
|
|
- `agent/` - Go binary installed on monitored hosts.
|
|
- `server/` - Python/FastAPI backend with PostgreSQL storage.
|
|
- `web/` - Next.js operator dashboard.
|
|
|
|
The server owns incident and notification lifecycle. The agent sends facts only.
|
|
The web UI is read-only for monitoring state; agent admission and blacklist
|
|
controls are the v1 mutation surface.
|
|
|
|
Public API contracts live in `api/openapi.yaml`. Design and operations docs start
|
|
at `docs/index.md`.
|
|
|
|
## Non-Goals
|
|
|
|
Monlet 0.1.0 is intentionally not:
|
|
|
|
- a remote command runner;
|
|
- a remote config-push system;
|
|
- a Grafana replacement;
|
|
- a full incident-management platform;
|
|
- a multi-tenant RBAC product;
|
|
- a Kubernetes operator;
|
|
- a distributed server cluster.
|
|
|
|
## Development
|
|
|
|
Start with:
|
|
|
|
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.md](CONFIG_REFERENCE.md) ([Русский](CONFIG_REFERENCE.ru.md))
|
|
7. [docs/index.md](docs/index.md)
|
|
|
|
Dependency caches and virtual environments are kept inside the repository. See
|
|
the component READMEs for current local development commands.
|
|
|
|
## Status
|
|
|
|
Monlet is active early-stage software. The 0.1.0 release is usable for local
|
|
development, demos, and controlled internal deployments. Internal contracts may
|
|
still change while the public API remains versioned under `/api/v1`.
|
|
|
|
`0.1.0` is the product release version. `/api/v1` is the API namespace.
|
|
|
|
## License
|
|
|
|
MIT.
|