docs: rewrite overview, collectors, config, build_and_run, deploy; update README [author: Сергей Антропов https://devops.org.ru]
This commit is contained in:
parent
ad409950b8
commit
1402fceb0e
26
README.md
26
README.md
@ -2,17 +2,23 @@
|
|||||||
|
|
||||||
Автор: Сергей Антропов, сайт: https://devops.org.ru
|
Автор: Сергей Антропов, сайт: https://devops.org.ru
|
||||||
|
|
||||||
Модульный агент мониторинга на Go 1.22+. Поддерживает встроенные и внешние (exec) коллекторы, вывод в stdout и Kafka, systemd unit.
|
SensusAgent — модульный агент сбора метрик. Агент запускает коллекторы (встроенные и внешние exec) по расписанию, агрегирует их JSON-вывод и публикует в stdout или Kafka.
|
||||||
|
|
||||||
### Структура
|
Ключевые ссылки:
|
||||||
- src/core — ядро (конфиг, логирование, реестр коллекторов, раннер, вывод)
|
- Обзор и архитектура: `docs/overview.md`
|
||||||
- src/collectors — исходники Go-коллекторов (сборка в bin/agent/collectors)
|
- Конфигурация: `docs/config.md`
|
||||||
- bin/agent — бинарник и конфиги
|
- Коллекторы (создание и сборка): `docs/collectors.md`
|
||||||
|
- Сборка и запуск (Make/Docker/Compose): `docs/build_and_run.md`
|
||||||
|
- Деплой (Ansible, systemd): `docs/deploy.md`
|
||||||
|
|
||||||
### Сборка и запуск
|
Быстрый старт:
|
||||||
Подробно см. `app/docs/README.md`.
|
```bash
|
||||||
|
make collectors-linux
|
||||||
### Конфигурация
|
make build-linux
|
||||||
Все настройки, включая коллекторы, находятся в `bin/agent/config.yaml`.
|
make run
|
||||||
|
```
|
||||||
|
|
||||||
|
Конфигурация:
|
||||||
|
- Основной файл: `bin/agent/config.yaml`
|
||||||
|
- Переопределения: `CONFIG_PATH`, `LOG_LEVEL`
|
||||||
|
|
||||||
|
|||||||
11
docs/README.md
Normal file
11
docs/README.md
Normal file
@ -0,0 +1,11 @@
|
|||||||
|
## SensusAgent — документация
|
||||||
|
|
||||||
|
Автор: Сергей Антропов, сайт: https://devops.org.ru
|
||||||
|
|
||||||
|
Содержание:
|
||||||
|
- Обзор: `overview.md`
|
||||||
|
- Конфигурация: `config.md`
|
||||||
|
- Коллекторы: `collectors.md`
|
||||||
|
- Сборка и запуск: `build_and_run.md`
|
||||||
|
- Деплой: `deploy.md`
|
||||||
|
|
||||||
34
docs/build_and_run.md
Normal file
34
docs/build_and_run.md
Normal file
@ -0,0 +1,34 @@
|
|||||||
|
### Сборка и запуск (через Docker/Make)
|
||||||
|
|
||||||
|
Автор: Сергей Антропов, сайт: https://devops.org.ru
|
||||||
|
|
||||||
|
Требования:
|
||||||
|
- Docker и Docker Compose
|
||||||
|
|
||||||
|
Основные цели Makefile:
|
||||||
|
- `make collectors` — сборка коллекторов для текущей платформы
|
||||||
|
- `make collectors-linux` / `collectors-darwin` / `collectors-windows` — кросс-сборка
|
||||||
|
- `make build` / `build-linux` / `build-darwin` — сборка агента
|
||||||
|
- `make run` — одноразовый запуск и вывод JSON (через jq)
|
||||||
|
- `make agent` — запуск агента с логированием в stdout
|
||||||
|
|
||||||
|
Примеры:
|
||||||
|
```bash
|
||||||
|
make collectors-linux
|
||||||
|
make build-linux
|
||||||
|
make run
|
||||||
|
```
|
||||||
|
|
||||||
|
Docker-образ разработки:
|
||||||
|
- Файл `Dockerfile` собирает бинарь агента `sensusagent` и часть коллекторов в `/bin/agent`
|
||||||
|
|
||||||
|
Docker Compose (упрощенный запуск):
|
||||||
|
Файл `docker-compose.yml` поднимает сервис `agent`.
|
||||||
|
```bash
|
||||||
|
docker compose up --build
|
||||||
|
```
|
||||||
|
|
||||||
|
Переменные окружения:
|
||||||
|
- `CONFIG_PATH` — путь к конфигу (по умолчанию `/bin/agent/config.yaml` в контейнере)
|
||||||
|
- `LOG_LEVEL` — `error` | `info` | `debug`
|
||||||
|
|
||||||
48
docs/collectors.md
Normal file
48
docs/collectors.md
Normal file
@ -0,0 +1,48 @@
|
|||||||
|
### Коллекторы
|
||||||
|
|
||||||
|
Автор: Сергей Антропов, сайт: https://devops.org.ru
|
||||||
|
|
||||||
|
Коллектор — это модуль, который исполняется агентом по расписанию и выводит результат в формате JSON в stdout. Агент объединяет вывод всех активных коллекторов в один JSON-документ.
|
||||||
|
|
||||||
|
Размещение исходников и артефактов:
|
||||||
|
- Исходники Go-коллекторов: `src/collectors/<name>`
|
||||||
|
- Собранные бинарники/скрипты: `bin/agent/collectors/<name>`
|
||||||
|
|
||||||
|
Требования к коллектору:
|
||||||
|
- Вывод строго в формате JSON в stdout (одна строка или валидный JSON-объект)
|
||||||
|
- Отсутствие побочного вывода в stderr/stdout кроме JSON (для корректного парсинга)
|
||||||
|
- Завершение за время, не превышающее `timeout` в конфигурации
|
||||||
|
|
||||||
|
Пример внешнего скрипта-коллектора (`bin/agent/collectors/sample.sh`):
|
||||||
|
```bash
|
||||||
|
#!/usr/bin/env sh
|
||||||
|
set -eu
|
||||||
|
echo '{"sample": {"ok": true, "ts": '"$(date +%s)"'}}'
|
||||||
|
```
|
||||||
|
|
||||||
|
Пример описания коллектора в `bin/agent/config.yaml`:
|
||||||
|
```yaml
|
||||||
|
collectors:
|
||||||
|
system:
|
||||||
|
enabled: true
|
||||||
|
type: exec
|
||||||
|
key: system
|
||||||
|
interval: "30s"
|
||||||
|
timeout: "8s"
|
||||||
|
exec: "./collectors/system"
|
||||||
|
platforms: [linux]
|
||||||
|
```
|
||||||
|
|
||||||
|
Сборка Go-коллекторов через Makefile (в Docker):
|
||||||
|
```bash
|
||||||
|
make collectors # текущая платформа
|
||||||
|
make collectors-linux # linux/amd64
|
||||||
|
make collectors-darwin # darwin/arm64
|
||||||
|
```
|
||||||
|
|
||||||
|
Рекомендации по разработке:
|
||||||
|
- Следуйте единому JSON-стилю и ключам, не допускайте дублирования имен ключей между коллекторами
|
||||||
|
- Логирование делайте в stderr, чтобы не мешать JSON
|
||||||
|
- Ограничивайте потребление ресурсов и время выполнения
|
||||||
|
- На стороне агента используйте `interval` ≥ 10s для тяжелых коллекторов
|
||||||
|
|
||||||
86
docs/config.md
Normal file
86
docs/config.md
Normal file
@ -0,0 +1,86 @@
|
|||||||
|
### Конфигурация
|
||||||
|
|
||||||
|
Автор: Сергей Антропов, сайт: https://devops.org.ru
|
||||||
|
|
||||||
|
Основной файл конфигурации: `bin/agent/config.yaml`. Путь можно переопределить переменной окружения `CONFIG_PATH`.
|
||||||
|
|
||||||
|
Ключевые секции:
|
||||||
|
- `mode`: режим вывода (`stdout` | `kafka` | `auto`)
|
||||||
|
- `log_level`: уровень логирования (`error` | `info` | `debug`)
|
||||||
|
- `kafka`: параметры продюсера (если используется `mode: kafka`)
|
||||||
|
- `collectors`: список коллекторов и их расписание
|
||||||
|
|
||||||
|
Пример полного файла `config.yaml`:
|
||||||
|
```yaml
|
||||||
|
mode: auto # stdout | kafka | auto
|
||||||
|
log_level: info
|
||||||
|
|
||||||
|
kafka:
|
||||||
|
enabled: false
|
||||||
|
brokers: ["kafka:9092"]
|
||||||
|
topic: "sensus.metrics"
|
||||||
|
client_id: "sensusagent"
|
||||||
|
enable_tls: false
|
||||||
|
timeout: "5s"
|
||||||
|
|
||||||
|
collectors:
|
||||||
|
system:
|
||||||
|
enabled: true
|
||||||
|
type: exec
|
||||||
|
key: system
|
||||||
|
interval: "30s"
|
||||||
|
timeout: "8s"
|
||||||
|
exec: "./collectors/system"
|
||||||
|
platforms: [linux]
|
||||||
|
uptime:
|
||||||
|
enabled: false
|
||||||
|
type: exec
|
||||||
|
key: uptime
|
||||||
|
interval: "10s"
|
||||||
|
timeout: "5s"
|
||||||
|
exec: "./collectors/uptime"
|
||||||
|
platforms: [darwin, linux, windows]
|
||||||
|
macos:
|
||||||
|
enabled: false
|
||||||
|
type: exec
|
||||||
|
key: macos
|
||||||
|
interval: "30s"
|
||||||
|
timeout: "10s"
|
||||||
|
exec: "./collectors/macos"
|
||||||
|
platforms: [darwin]
|
||||||
|
sample:
|
||||||
|
enabled: false
|
||||||
|
type: exec
|
||||||
|
key: sample
|
||||||
|
interval: "30s"
|
||||||
|
timeout: "5s"
|
||||||
|
exec: "./collectors/sample.sh"
|
||||||
|
platforms: [darwin, linux]
|
||||||
|
hba:
|
||||||
|
enabled: true
|
||||||
|
type: exec
|
||||||
|
key: hba
|
||||||
|
interval: "60s"
|
||||||
|
timeout: "10s"
|
||||||
|
exec: "./collectors/hba"
|
||||||
|
platforms: [linux]
|
||||||
|
```
|
||||||
|
|
||||||
|
Пояснения по полям коллектора:
|
||||||
|
- `enabled`: включить/выключить коллектор
|
||||||
|
- `type`: тип коллектора, `exec` — внешний бинарь/скрипт
|
||||||
|
- `key`: ключ верхнего уровня в итоговом JSON
|
||||||
|
- `interval`: минимальный интервал между запусками (Go duration)
|
||||||
|
- `timeout`: максимальное время выполнения (Go duration)
|
||||||
|
- `exec`: относительный путь к исполняемому файлу в каталоге `bin/agent/collectors`
|
||||||
|
- `platforms`: список платформ, на которых допустим запуск (`linux`, `darwin`, `windows`)
|
||||||
|
|
||||||
|
Переменные окружения:
|
||||||
|
- `CONFIG_PATH` — путь к `config.yaml`
|
||||||
|
- `LOG_LEVEL` — уровень логирования (`error`, `info`, `debug`)
|
||||||
|
|
||||||
|
Советы по конфигурации:
|
||||||
|
- Для тяжелых коллекторов увеличивайте `interval` и `timeout`
|
||||||
|
- При использовании Kafka установите `kafka.enabled: true` и корректные `brokers`/`topic`
|
||||||
|
- Следите, чтобы ключи `key` у разных коллекторов не пересекались
|
||||||
|
|
||||||
44
docs/deploy.md
Normal file
44
docs/deploy.md
Normal file
@ -0,0 +1,44 @@
|
|||||||
|
### Деплой
|
||||||
|
|
||||||
|
Автор: Сергей Антропов, сайт: https://devops.org.ru
|
||||||
|
|
||||||
|
Варианты развертывания:
|
||||||
|
- Docker Compose: файл `docker-compose.yml`
|
||||||
|
- Systemd сервис: через роль `runner/deploy-service` (юнит находится в `runner/sensusagent.service` при необходимости)
|
||||||
|
- Ansible-плейбуки: `runner/deploy`, `runner/delete`, а также service-варианты
|
||||||
|
|
||||||
|
Подготовка удаленного хоста:
|
||||||
|
- Доступ по SSH (ключ находится у оператора)
|
||||||
|
- Права `sudo` для установки зависимостей
|
||||||
|
|
||||||
|
Быстрый деплой (одноразовый запуск агента без systemd):
|
||||||
|
```bash
|
||||||
|
make deploy
|
||||||
|
```
|
||||||
|
Что делает команда:
|
||||||
|
- Собирает linux-бинарь агента и коллектора в Docker
|
||||||
|
- Копирует `bin/agent/agent`, `bin/agent/config.yaml`, `bin/agent/collectors/*` на удаленный хост в `/opt/sensusagent`
|
||||||
|
- Обеспечивает зависимости (например, `sysstat`, `smartmontools` и др.)
|
||||||
|
|
||||||
|
Удаление установленного агента (без systemd):
|
||||||
|
```bash
|
||||||
|
make delete
|
||||||
|
```
|
||||||
|
|
||||||
|
Деплой и запуск через systemd:
|
||||||
|
```bash
|
||||||
|
make deploy-service
|
||||||
|
```
|
||||||
|
|
||||||
|
Остановка и очистка systemd-варианта:
|
||||||
|
```bash
|
||||||
|
make delete-service
|
||||||
|
```
|
||||||
|
|
||||||
|
Переменные Ansible:
|
||||||
|
- `LOCAL_BIN_DIR` — локальный каталог с собранным агентом (по умолчанию `./bin/agent`)
|
||||||
|
- `remote_dir` — удаленный каталог установки (по умолчанию `/opt/sensusagent` в плейбуках)
|
||||||
|
|
||||||
|
Инвентори:
|
||||||
|
- Файл `runner/inventory.ini` определяет целевые хосты и параметры подключения
|
||||||
|
|
||||||
46
docs/overview.md
Normal file
46
docs/overview.md
Normal file
@ -0,0 +1,46 @@
|
|||||||
|
### Обзор
|
||||||
|
|
||||||
|
Автор: Сергей Антропов, сайт: https://devops.org.ru
|
||||||
|
|
||||||
|
SensusAgent — модульный агент сбора метрик и инвентарных данных. Агент запускает встроенные и внешние (exec) коллекторы по расписанию, объединяет их JSON-вывод в единый документ и публикует в выбранный канал вывода (stdout, Kafka или auto-режим).
|
||||||
|
|
||||||
|
Основные возможности:
|
||||||
|
- Запуск коллекторов как внешних исполняемых файлов из `bin/agent/collectors` и как встроенных Go-бинарей
|
||||||
|
- Единый JSON-формат вывода для удобной интеграции
|
||||||
|
- Гибкая конфигурация через `bin/agent/config.yaml` и переменные окружения
|
||||||
|
- Кроссплатформенная сборка через Docker и Makefile (без локальной Go-сборки)
|
||||||
|
- Деплой и удаление через Ansible (`make deploy`, `make delete`, а также варианты с systemd)
|
||||||
|
|
||||||
|
Архитектура и компоненты репозитория:
|
||||||
|
- `src/core/*` — ядро агента (конфигурация, реестр коллекторов, раннер, логирование, вывод)
|
||||||
|
- `src/collectors/*` — исходники Go-коллекторов (сборка в `bin/agent/collectors`)
|
||||||
|
- `bin/agent` — исполняемые файлы и конфиги агента (`config.yaml`, собранные коллекторы)
|
||||||
|
- `runner/*` — сценарии Ansible для деплоя/удаления (и для systemd)
|
||||||
|
- `docs/*` — документация проекта
|
||||||
|
|
||||||
|
Поток выполнения:
|
||||||
|
1. Агент загружает конфигурацию из `bin/agent/config.yaml` (путь можно переопределить `CONFIG_PATH`)
|
||||||
|
2. Инициализирует логирование по уровню `LOG_LEVEL`
|
||||||
|
3. Регистрирует и планирует запуск коллекторов согласно их `interval` и `timeout`
|
||||||
|
4. Исполняет коллектора (встроенные или `type: exec`), читает JSON из stdout
|
||||||
|
5. Объединяет данные в общий JSON-документ и публикует в stdout или Kafka (в зависимости от `mode`)
|
||||||
|
|
||||||
|
Режимы вывода (`mode`):
|
||||||
|
- `stdout` — печать JSON в стандартный вывод
|
||||||
|
- `kafka` — отправка в Kafka-топик
|
||||||
|
- `auto` — автоматически выбирает канал (например, stdout, если Kafka отключена)
|
||||||
|
|
||||||
|
Переменные окружения (основные):
|
||||||
|
- `CONFIG_PATH` — путь к конфигурации (по умолчанию `./bin/agent/config.yaml`)
|
||||||
|
- `LOG_LEVEL` — уровень логирования (`error`, `info`, `debug`)
|
||||||
|
|
||||||
|
Поддерживаемые платформы:
|
||||||
|
- Linux (агент и коллекторы)
|
||||||
|
- macOS (часть коллекторов и сборок)
|
||||||
|
- Windows (ограниченно для некоторых коллекторов)
|
||||||
|
|
||||||
|
См. также:
|
||||||
|
- Конфигурация: `docs/config.md`
|
||||||
|
- Коллекторы: `docs/collectors.md`
|
||||||
|
- Сборка/запуск: `docs/build_and_run.md`
|
||||||
|
- Деплой: `docs/deploy.md`
|
||||||
Loading…
x
Reference in New Issue
Block a user