monlet/CONFIG_REFERENCE.ru.md

English | Русский

Monlet: краткий справочник по настройкам

Monlet состоит из агента на хостах и центрального сервера. Агент сам генерирует локальный ключ в state_dir/agent.key; сервер видит новый ключ как pending, пока оператор не примет агента в UI.

Agent TOML

Файл: обычно /etc/monlet/agent.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 или переменные контейнера.

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.

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.