230 lines
13 KiB
Markdown
230 lines
13 KiB
Markdown
# Monlet: краткий справочник по настройкам
|
||
|
||
Monlet состоит из агента на хостах и центрального сервера. Агент сам генерирует локальный ключ в `state_dir/agent.key`; сервер видит новый ключ как `pending`, пока оператор не примет агента в UI.
|
||
|
||
## Agent TOML
|
||
|
||
Файл: обычно `/etc/monlet/agent.toml`.
|
||
|
||
```toml
|
||
# Необязательно. Если не задано, используется hostname ОС.
|
||
# agent_id = "host-01"
|
||
|
||
state_dir = "/var/lib/monlet-agent"
|
||
|
||
[labels]
|
||
env = "prod"
|
||
role = "api"
|
||
|
||
[server]
|
||
enabled = true
|
||
url = "https://monlet.example.com"
|
||
heartbeat_interval = "10s"
|
||
batch_interval = "10s"
|
||
|
||
[metrics]
|
||
enabled = true
|
||
listen = "127.0.0.1:9465"
|
||
|
||
[[checks]]
|
||
id = "disk_root"
|
||
name = "Root disk usage"
|
||
command = '''
|
||
/usr/local/lib/monlet/check_disk_root.sh --warn 80 --crit 90
|
||
'''
|
||
interval = "60s"
|
||
timeout = "10s"
|
||
notifications_enabled = true
|
||
resource_limits = { cpu_time = "5s", memory = "256MiB", open_files = 128 }
|
||
|
||
[[checks]]
|
||
id = "daily_backup"
|
||
name = "Daily backup freshness"
|
||
command = "/usr/local/lib/monlet/check_backup_freshness.sh"
|
||
cron = "CRON_TZ=UTC 15 6 * * *"
|
||
timeout = "2m"
|
||
```
|
||
|
||
Ключи:
|
||
|
||
- `agent_id` — стабильный ID агента; необязателен, по умолчанию hostname.
|
||
- `state_dir` — локальное состояние, ключ агента и spool.
|
||
- `[labels]` — метки инвентаря; секреты сюда не класть.
|
||
- `server.enabled` — отправлять heartbeat/events на сервер.
|
||
- `server.url` — базовый URL сервера.
|
||
- `metrics.enabled` — поднять Prometheus `/metrics`.
|
||
- `metrics.listen` — адрес `/metrics`.
|
||
- `checks[].id` — стабильный ID проверки.
|
||
- `checks[].command` — shell-команда строкой; однострочно в `"..."`, многострочно в `'''...'''`.
|
||
- `checks[].interval` — период запуска (`60s`, `5m`, `1h`); обязателен, если не задан `checks[].cron`.
|
||
- `checks[].cron` — cron-style расписание; обязателен, если не задан `checks[].interval`. Поддерживаются стандартные 5 полей, `@hourly`/`@daily` и `CRON_TZ=...`; seconds-format, `@every` и `@reboot` отклоняются.
|
||
- `checks[].timeout` — таймаут; при таймауте результат `critical`.
|
||
- `checks[].notifications_enabled` — разрешить серверные уведомления по этой проверке.
|
||
- `checks[].resource_limits` — опциональные лимиты процесса: CPU-время, virtual memory, open files.
|
||
|
||
Для каждой проверки нужно задать ровно один способ расписания: `interval` или `cron`. Interval-проверки запускаются сразу после старта/reload, затем по периоду. Cron-проверки ждут ближайший cron-slot и не запускаются немедленно при старте.
|
||
|
||
Exit code: `0=ok`, `1=warning`, `2=critical`, `3+=unknown`.
|
||
|
||
Env агента:
|
||
|
||
- `MONLET_AGENT_MAX_CHECKS` — максимум проверок в конфиге (по умолчанию 256). Лимит ограничивает кардинальность метрики `{check_id}`. Положительное целое; превышение лимита — ошибка загрузки конфига.
|
||
|
||
Reload:
|
||
|
||
- `systemctl reload monlet-agent` перечитывает локальный TOML через `SIGHUP`.
|
||
- Ошибочный config не применяется, старый продолжает работать.
|
||
- Уже запущенный check при reload не убивается, а доживает до своего `timeout`.
|
||
- При смене расписания interval-check запускается после текущего in-flight run; cron-check ждёт следующий cron-slot.
|
||
- Для изменения `agent_id`, `state_dir`, `server.*`, `metrics.*` нужен restart.
|
||
|
||
## Server env
|
||
|
||
Файл: `.env` или переменные контейнера.
|
||
|
||
```env
|
||
MONLET_AUTH_TOKEN=replace-with-random-ui-token
|
||
MONLET_DATABASE_URL=postgresql+asyncpg://monlet:monlet@postgres:5432/monlet
|
||
MONLET_LOG_LEVEL=INFO
|
||
|
||
MONLET_HOST=0.0.0.0
|
||
MONLET_PORT=8000
|
||
|
||
MONLET_BODY_LIMIT_BYTES=1048576
|
||
MONLET_OUTPUT_MAX_BYTES=8192
|
||
MONLET_MAX_BATCH_EVENTS=200
|
||
|
||
MONLET_ENABLE_DETECTOR=true
|
||
MONLET_STALE_AFTER_SEC=20
|
||
MONLET_DEAD_AFTER_SEC=30
|
||
MONLET_DETECTOR_TICK_SEC=5
|
||
|
||
MONLET_DB_POOL_SIZE=10
|
||
MONLET_DB_MAX_OVERFLOW=10
|
||
MONLET_DB_POOL_TIMEOUT_SEC=30
|
||
MONLET_DB_POOL_RECYCLE_SEC=1800
|
||
|
||
MONLET_EVENTS_RETENTION_MONTHS=36
|
||
MONLET_EVENTS_FUTURE_PARTITIONS=3
|
||
MONLET_PARTITION_MAINTENANCE_INTERVAL_SEC=3600
|
||
MONLET_OUTBOX_RETENTION_MAX_ROWS=50000
|
||
MONLET_OUTBOX_PRUNE_BATCH_SIZE=5000
|
||
|
||
MONLET_EVENT_DEDUP_RETENTION_DAYS=30
|
||
MONLET_EVENT_DEDUP_PRUNE_BATCH_SIZE=5000
|
||
|
||
MONLET_MAX_PENDING_AGENTS=10000
|
||
MONLET_PENDING_AGENT_TTL_DAYS=7
|
||
MONLET_PENDING_AGENT_PRUNE_BATCH_SIZE=1000
|
||
|
||
MONLET_ENABLE_NOTIFIER_WORKER=true
|
||
MONLET_NOTIFIER_TICK_SEC=5
|
||
MONLET_NOTIFIER_BATCH_SIZE=20
|
||
MONLET_NOTIFIER_CONCURRENCY=4
|
||
MONLET_NOTIFIER_MAX_ATTEMPTS=8
|
||
MONLET_NOTIFIER_LEASE_SEC=300
|
||
MONLET_NOTIFIER_HTTP_TIMEOUT_SEC=10
|
||
MONLET_NOTIFIER_INCLUDE_OUTPUT=true
|
||
MONLET_NOTIFIER_MAX_OUTPUT_BYTES=1024
|
||
MONLET_NOTIFICATION_TIME_ZONE=UTC
|
||
|
||
MONLET_NOTIFIER_DEBUG_ENABLED=true
|
||
MONLET_NOTIFIER_TELEGRAM_ENABLED=false
|
||
MONLET_NOTIFIER_WEBHOOK_ENABLED=false
|
||
MONLET_NOTIFIER_ALERTMANAGER_ENABLED=false
|
||
```
|
||
|
||
Основное:
|
||
|
||
- `MONLET_AUTH_TOKEN` — Bearer-токен(ы) для UI/operator API, не для агентов. Список через запятую/пробел для ротации.
|
||
- `MONLET_DATABASE_URL` — PostgreSQL DSN (`postgresql+asyncpg://...`).
|
||
- `MONLET_LOG_LEVEL` — уровень логирования.
|
||
- `MONLET_HOST` / `MONLET_PORT` — адрес и порт HTTP-сервера (по умолчанию `0.0.0.0:8000`).
|
||
|
||
Лимиты приёма:
|
||
|
||
- `MONLET_BODY_LIMIT_BYTES` — максимальный размер тела запроса (по умолчанию 1 MiB = 1048576).
|
||
- `MONLET_OUTPUT_MAX_BYTES` — лимит хранимого `output` события (по умолчанию 8192).
|
||
- `MONLET_MAX_BATCH_EVENTS` — максимум событий в одном batch (по умолчанию 200).
|
||
|
||
Liveness-детектор:
|
||
|
||
- `MONLET_ENABLE_DETECTOR` — включить фоновый пересчёт stale/dead (по умолчанию `true`).
|
||
- `MONLET_STALE_AFTER_SEC` — через сколько секунд без heartbeat агент становится `stale`.
|
||
- `MONLET_DEAD_AFTER_SEC` — через сколько секунд без heartbeat агент становится `dead`.
|
||
- `MONLET_DETECTOR_TICK_SEC` — как часто сервер пересчитывает liveness.
|
||
|
||
Пул БД (тюнинг под нагрузку):
|
||
|
||
- `MONLET_DB_POOL_SIZE` — постоянных соединений в пуле (по умолчанию 10).
|
||
- `MONLET_DB_MAX_OVERFLOW` — дополнительных соединений сверх пула (по умолчанию 10).
|
||
- `MONLET_DB_POOL_TIMEOUT_SEC` — ожидание свободного соединения (по умолчанию 30).
|
||
- `MONLET_DB_POOL_RECYCLE_SEC` — пересоздание соединения по возрасту (по умолчанию 1800).
|
||
|
||
Хранение и обслуживание:
|
||
|
||
- `MONLET_EVENTS_RETENTION_MONTHS` — хранение event-партиций (по умолчанию 36).
|
||
- `MONLET_EVENTS_FUTURE_PARTITIONS` — сколько будущих месячных партиций создавать заранее (по умолчанию 3).
|
||
- `MONLET_PARTITION_MAINTENANCE_INTERVAL_SEC` — период обслуживания партиций и prune (по умолчанию 3600).
|
||
- `MONLET_OUTBOX_RETENTION_MAX_ROWS` — верхняя граница строк в outbox; лишние обрезаются (по умолчанию 50000).
|
||
- `MONLET_OUTBOX_PRUNE_BATCH_SIZE` — размер пакета при очистке terminal outbox-записей (по умолчанию 5000).
|
||
- `MONLET_EVENT_DEDUP_RETENTION_DAYS` — хранение записей идемпотентности `event_id` (по умолчанию 30).
|
||
- `MONLET_EVENT_DEDUP_PRUNE_BATCH_SIZE` — размер пакета при очистке dedup-записей (по умолчанию 5000).
|
||
- `MONLET_MAX_PENDING_AGENTS` — лимит новых непринятых агентов (по умолчанию 10000).
|
||
- `MONLET_PENDING_AGENT_TTL_DAYS` — очистка старых pending-ключей (по умолчанию 7).
|
||
- `MONLET_PENDING_AGENT_PRUNE_BATCH_SIZE` — размер пакета при очистке старых pending-ключей (по умолчанию 1000).
|
||
|
||
Notifier worker:
|
||
|
||
- `MONLET_ENABLE_NOTIFIER_WORKER` — включить worker доставки уведомлений (по умолчанию `true`).
|
||
- `MONLET_NOTIFIER_TICK_SEC` — период опроса outbox (по умолчанию 5).
|
||
- `MONLET_NOTIFIER_BATCH_SIZE` — сколько outbox-записей worker забирает за тик (по умолчанию 20).
|
||
- `MONLET_NOTIFIER_CONCURRENCY` — параллелизм доставки внутри тика (по умолчанию 4).
|
||
- `MONLET_NOTIFIER_MAX_ATTEMPTS` — максимум попыток доставки до перевода в permanent failure (по умолчанию 8).
|
||
- `MONLET_NOTIFIER_LEASE_SEC` — аренда записи на время доставки, чтобы её не взял другой worker (по умолчанию 300).
|
||
- `MONLET_NOTIFIER_HTTP_TIMEOUT_SEC` — таймаут HTTP-доставки (по умолчанию 10).
|
||
- `MONLET_NOTIFIER_INCLUDE_OUTPUT` — включать ли текст `output` в уведомления (по умолчанию `true`).
|
||
- `MONLET_NOTIFIER_MAX_OUTPUT_BYTES` — обрезка `output` в уведомлении после редакции (по умолчанию 1024).
|
||
- `MONLET_NOTIFICATION_TIME_ZONE` — таймзона человекочитаемых дат в уведомлениях.
|
||
|
||
Notifier каналы:
|
||
|
||
- Telegram: `MONLET_NOTIFIER_TELEGRAM_ENABLED=true`, `MONLET_NOTIFIER_TELEGRAM_TOKEN`, `MONLET_NOTIFIER_TELEGRAM_CHAT_ID`.
|
||
- Webhook: `MONLET_NOTIFIER_WEBHOOK_ENABLED=true`, `MONLET_NOTIFIER_WEBHOOK_URL`, опционально `MONLET_NOTIFIER_WEBHOOK_TOKEN`.
|
||
- Alertmanager: `MONLET_NOTIFIER_ALERTMANAGER_ENABLED=true`, `MONLET_NOTIFIER_ALERTMANAGER_URL`.
|
||
- Debug/log: `MONLET_NOTIFIER_DEBUG_ENABLED=true`.
|
||
|
||
## Web env
|
||
|
||
Веб-UI читает API/auth/timezone-настройки из env. Без auth-настроек read-only страницы доступны локально, но admission-мутации возвращают `403`.
|
||
|
||
```env
|
||
MONLET_API_BASE_URL=http://127.0.0.1:8000
|
||
MONLET_API_TOKEN=replace-with-server-token
|
||
MONLET_WEB_TIME_ZONE=UTC
|
||
MONLET_WEB_AUTH_USERNAME=admin
|
||
MONLET_WEB_AUTH_PASSWORD=replace-with-strong-password
|
||
MONLET_WEB_SESSION_SECRET=replace-with-random-32-bytes-min
|
||
MONLET_WEB_SESSION_TTL_SEC=604800
|
||
NEXT_PUBLIC_MONLET_POLL_MS=10000
|
||
# или вместо локального логина — доверие reverse-proxy:
|
||
# MONLET_WEB_TRUST_PROXY_AUTH=true
|
||
```
|
||
|
||
- `MONLET_API_BASE_URL` — базовый URL сервера для server-side fetch.
|
||
- `MONLET_API_TOKEN` — Bearer-токен для запросов UI к серверу; в браузер не передаётся.
|
||
- `MONLET_WEB_TIME_ZONE` — IANA timezone для отображения дат (по умолчанию `UTC`).
|
||
- `MONLET_WEB_AUTH_USERNAME` / `MONLET_WEB_AUTH_PASSWORD` — учётные данные локального cookie-логина.
|
||
- `MONLET_WEB_SESSION_SECRET` — секрет подписи сессии, минимум 32 байта; короче — UI считает auth неправильно настроенным.
|
||
- `MONLET_WEB_SESSION_TTL_SEC` — срок жизни сессии (по умолчанию 604800 = 7 дней).
|
||
- `MONLET_WEB_TRUST_PROXY_AUTH` — `true` включает доверие заголовку `X-Forwarded-User` от reverse-proxy. Несовместимо с локальным логином: одновременная настройка обоих режимов — ошибка (UI отвечает `500`).
|
||
- `NEXT_PUBLIC_MONLET_POLL_MS` — интервал браузерного polling в миллисекундах (по умолчанию 10000); для production-сборок Next.js это build-time переменная.
|
||
|
||
## Минимальная схема
|
||
|
||
1. Сервер стартует с PostgreSQL и `MONLET_AUTH_TOKEN`.
|
||
2. Агент стартует с TOML, создаёт `state_dir/agent.key` и шлёт heartbeat.
|
||
3. Новый агент появляется в UI как `pending`.
|
||
4. Оператор принимает агента.
|
||
5. После accept сервер начинает учитывать events, checks, incidents и notifications.
|