Skip to main content

MetricForge — обзор проекта

Что это и зачем​

MetricForge решает одну конкретную задачу: собирать числовые метрики с множества хостов и отправлять их в InfluxDB, не требуя сложной инфраструктуры.

Стандартные стеки (Prometheus + exporters, Telegraf, Datadog agent) либо слишком тяжёлые, либо требуют развёртывания и поддержки отдельного сервиса на каждом хосте. MetricForge идёт другим путём: на хосте живёт простой bash-агент (один скрипт, установка — одна команда curl | bash). Агент периодически тянет конфиг с сервера, выполняет описанные в нём shell-команды и отправляет результаты обратно. Весь конфиг и управление — в одном месте.

Дополнительные задачи: централизованный запуск произвольных скриптов на хостах (Executor) и инвентаризация SNMP-устройств в сети.

Один процесс, один файл БД, никаких брокеров. Деплой — docker compose up.

Основные понятия​

Инвентарь: Group и Host​

Group — инвентарная единица. Объединяет хосты, задаёт интервал опроса и InfluxDB-подключение. Примеры: Production Servers, Network Core, Lab.

Host бывает двух типов:

  • agent — bash-агент на хосте сам выполняет команды и пушит результаты.
  • snmp — сервер MetricForge опрашивает устройство по SNMP сам (роутеры, свитчи, любое сетевое железо).

Tag — метка для хостов. Используется для гибкого назначения коллекций и метрик сразу на группу хостов по признаку.

Мониторинг: Collection, Metric, Collector​

Collection — переиспользуемый набор метрик и коллекторов. Описать один раз → назначить на любые группы, хосты или теги. Хранит ссылку на Credential и имя bucket.

Metric — описание того, что измерять:

  • command — shell-команда (агент выполняет, должна вывести одно число).
  • oid — SNMP OID (сервер опрашивает сам).

Collector — специализированный источник динамических метрик: Docker, PostgreSQL, Redis, Proxmox. Сервер раскрывает коллектор в обычные метрики до отправки агенту — агентский протокол не меняется. Один коллектор порождает отдельную серию на каждый объект (контейнер, БД, ноду).

Credential — InfluxDB-подключение (URL, org, token). Один Credential переиспользуется в нескольких коллекциях.

Назначения (Assignments)​

Коллекция назначается явно на group / host / tag. Приоритет при конфликте: host > tag ≈ group. Метрику можно точечно переопределить через metric_assignments (включить/выключить на конкретном хосте поверх коллекции).

Для разных окружений одна коллекция может писать в разные InfluxDB bucket через bucket_override на назначении:

Docker Monitoring → Production  (bucket: prod)
Docker Monitoring → Dev         (bucket: dev)
Docker Monitoring → Lab         (bucket: lab)

Поток метрики: от команды до InfluxDB​

Каждый /push одновременно является heartbeat'ом: сервер обновляет hosts.status = online. Если хост молчит дольше 3× interval_s — отмечается как устаревший в UI.

Executor​

Задачи запускаются по расписанию (interval_s) или вручную. Результат — файл на диске сервера, доступен из UI.

Что реализовано сейчас​

Управление инфраструктурой​

  • Создание групп, хостов (agent и SNMP), credentials, тегов.
  • One-liner установка агента через UI (кнопка Setup → curl | bash).
  • Инвентаризация SNMP-сети: сканирование CIDR-диапазона, fingerprint вендора/ОС, импорт как хостов.
  • Keepalive SNMP-устройств: online → warning → offline с Telegram-алертами.
  • Orphan tracking: хосты без регистрации — видны в UI, «принять» одним кликом.

Сбор метрик​

  • Shell-метрики через агента и SNMP-метрики через server-side poller.
  • Гибкое назначение: коллекции и метрики на group/host/tag, приоритет host > tag/group.
  • Collections: переиспользуемые бандлы, YAML-экспорт/импорт.
  • Docker Collector: метрики per-container (CPU%, Memory%) без изменения протокола.
  • Bucket per-collection; multi-environment routing через bucket_override.

Executor​

  • Задачи (shell/python), расписание, ручной запуск.
  • Назначение на group/host, хранение артефактов, retention.

Runtime Observability​

  • Страница хоста: последние значения метрик, статус, длительность, stderr.
  • История прогонов с фильтрацией, heartbeat/staleness.

Интеграции​

  • AWX: деплой агентов и sync инвентаря через Ansible Automation Controller.
  • Telegram: алерты offline/online для SNMP-устройств.
  • SNMP Profiles (YAML): описания вендоров для fingerprint при сканировании.

Безопасность​

  • Сессионная аутентификация (httponly cookie, bcrypt), роли admin/viewer.

Чего нет (в планах)​

  • Multi-tenancy / RBAC — сейчас admin (полный доступ) или viewer (только чтение). Нельзя ограничить доступ к отдельным группам.
  • Ротация агентских токенов — токен детерминирован (hostname + секрет), явного механизма ротации нет.
  • Kubernetes / Security Audit / Package Management Collectors — место в реестре зарезервировано.
  • Async event bus — контракты между модулями сейчас синхронные. Переход на async шину (алерты на изменение статуса метрики, вебхуки) подготовлен архитектурно, но не открыт.
  • High Availability — один процесс, один SQLite-файл. Горизонтальное масштабирование намеренно вне области.
  • Group-independent метрики — YAML-импорт метрик сейчас требует целевой группы. Полностью group-independent хранение метрик требует отдельной миграции.

Стек​

СлойТехнология
BackendPython 3.11+, FastAPI, Uvicorn
Хранилище конфигаSQLite (WAL-mode)
Хранилище метрикInfluxDB v2 (внешний)
FrontendReact 18, Vite, React Query v5
Агент на хостеbash + curl + jq
КонтейнеризацияDocker / docker compose