From 1402fceb0e4030d6831f0083796b3186bed19f52 Mon Sep 17 00:00:00 2001
From: Sergey Antropoff <sergey@antropoff.ru>
Date: Mon, 8 Sep 2025 15:19:13 +0300
Subject: [PATCH] =?UTF-8?q?docs:=20rewrite=20overview,=20collectors,=20con?=
 =?UTF-8?q?fig,=20build=5Fand=5Frun,=20deploy;=20update=20README=20[author?=
 =?UTF-8?q?:=20=D0=A1=D0=B5=D1=80=D0=B3=D0=B5=D0=B9=20=D0=90=D0=BD=D1=82?=
 =?UTF-8?q?=D1=80=D0=BE=D0=BF=D0=BE=D0=B2=20https://devops.org.ru]?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md             | 26 ++++++++-----
 docs/README.md        | 11 ++++++
 docs/build_and_run.md | 34 +++++++++++++++++
 docs/collectors.md    | 48 ++++++++++++++++++++++++
 docs/config.md        | 86 +++++++++++++++++++++++++++++++++++++++++++
 docs/deploy.md        | 44 ++++++++++++++++++++++
 docs/overview.md      | 46 +++++++++++++++++++++++
 7 files changed, 285 insertions(+), 10 deletions(-)
 create mode 100644 docs/README.md
 create mode 100644 docs/build_and_run.md
 create mode 100644 docs/collectors.md
 create mode 100644 docs/config.md
 create mode 100644 docs/deploy.md
 create mode 100644 docs/overview.md

diff --git a/README.md b/README.md
index 2dae1f9..6ec67e8 100644
--- a/README.md
+++ b/README.md
@@ -2,17 +2,23 @@
 
 Автор: Сергей Антропов, сайт: https://devops.org.ru
 
-Модульный агент мониторинга на Go 1.22+. Поддерживает встроенные и внешние (exec) коллекторы, вывод в stdout и Kafka, systemd unit.
+SensusAgent — модульный агент сбора метрик. Агент запускает коллекторы (встроенные и внешние exec) по расписанию, агрегирует их JSON-вывод и публикует в stdout или Kafka.
 
-### Структура
-- src/core — ядро (конфиг, логирование, реестр коллекторов, раннер, вывод)
-- src/collectors — исходники Go-коллекторов (сборка в bin/agent/collectors)
-- bin/agent — бинарник и конфиги
+Ключевые ссылки:
+- Обзор и архитектура: `docs/overview.md`
+- Конфигурация: `docs/config.md`
+- Коллекторы (создание и сборка): `docs/collectors.md`
+- Сборка и запуск (Make/Docker/Compose): `docs/build_and_run.md`
+- Деплой (Ansible, systemd): `docs/deploy.md`
 
-### Сборка и запуск
-Подробно см. `app/docs/README.md`.
-
-### Конфигурация
-Все настройки, включая коллекторы, находятся в `bin/agent/config.yaml`.
+Быстрый старт:
+```bash
+make collectors-linux
+make build-linux
+make run
+```
 
+Конфигурация:
+- Основной файл: `bin/agent/config.yaml`
+- Переопределения: `CONFIG_PATH`, `LOG_LEVEL`
 
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..80b3d64
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,11 @@
+## SensusAgent — документация
+
+Автор: Сергей Антропов, сайт: https://devops.org.ru
+
+Содержание:
+- Обзор: `overview.md`
+- Конфигурация: `config.md`
+- Коллекторы: `collectors.md`
+- Сборка и запуск: `build_and_run.md`
+- Деплой: `deploy.md`
+
diff --git a/docs/build_and_run.md b/docs/build_and_run.md
new file mode 100644
index 0000000..fe999e2
--- /dev/null
+++ b/docs/build_and_run.md
@@ -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`
+
diff --git a/docs/collectors.md b/docs/collectors.md
new file mode 100644
index 0000000..a1416b7
--- /dev/null
+++ b/docs/collectors.md
@@ -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 для тяжелых коллекторов
+
diff --git a/docs/config.md b/docs/config.md
new file mode 100644
index 0000000..ddb3706
--- /dev/null
+++ b/docs/config.md
@@ -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` у разных коллекторов не пересекались
+
diff --git a/docs/deploy.md b/docs/deploy.md
new file mode 100644
index 0000000..4557b1e
--- /dev/null
+++ b/docs/deploy.md
@@ -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` определяет целевые хосты и параметры подключения
+
diff --git a/docs/overview.md b/docs/overview.md
new file mode 100644
index 0000000..52b18e7
--- /dev/null
+++ b/docs/overview.md
@@ -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`