From 55e796bc2b6ace822dd97f63a8cb1e8d3d7d8fda Mon Sep 17 00:00:00 2001
From: Sergey Antropoff <sergey@antropoff.ru>
Date: Mon, 8 Sep 2025 15:23:12 +0300
Subject: [PATCH] =?UTF-8?q?docs:=20Kafka=20details;=20systemd=20section;?=
 =?UTF-8?q?=20compose=20examples;=20CI/CD=20notes;=20FAQ=20[author:=20?=
 =?UTF-8?q?=D0=A1=D0=B5=D1=80=D0=B3=D0=B5=D0=B9=20=D0=90=D0=BD=D1=82=D1=80?=
 =?UTF-8?q?=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

---
 docs/README.md        |  7 +++++++
 docs/build_and_run.md | 22 ++++++++++++++++++++++
 docs/config.md        | 38 ++++++++++++++++++++++++++++++++++++++
 docs/deploy.md        | 32 ++++++++++++++++++++++++++++++++
 docs/faq.md           | 27 +++++++++++++++++++++++++++
 5 files changed, 126 insertions(+)
 create mode 100644 docs/faq.md

diff --git a/docs/README.md b/docs/README.md
index 80b3d64..a6bdf4e 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -9,3 +9,10 @@
 - Сборка и запуск: `build_and_run.md`
 - Деплой: `deploy.md`
 
+CI/CD:
+- Рекомендуется запускать `make lint` и `make test` в конвейере CI (Docker-окружение)
+- Перед релизом — `make build-linux` и `make collectors-linux`
+- Для автоматического деплоя можно триггерить `make deploy` с секретами SSH
+
+FAQ / Траблшутинг: см. `faq.md`
+
diff --git a/docs/build_and_run.md b/docs/build_and_run.md
index fe999e2..a5ddd1e 100644
--- a/docs/build_and_run.md
+++ b/docs/build_and_run.md
@@ -32,3 +32,25 @@ docker compose up --build
 - `CONFIG_PATH` — путь к конфигу (по умолчанию `/bin/agent/config.yaml` в контейнере)
 - `LOG_LEVEL` — `error` | `info` | `debug`
 
+Пример docker-compose с переопределениями:
+```yaml
+version: "3.9"
+services:
+  agent:
+    build: .
+    image: sensusagent:dev
+    environment:
+      - CONFIG_PATH=/bin/agent/config.yaml
+      - LOG_LEVEL=debug
+    volumes:
+      - ./bin/agent:/bin/agent:ro
+    entrypoint: ["/bin/agent/sensusagent", "--mode", "stdout"]
+```
+
+Полезные команды:
+```bash
+docker compose logs -f agent
+docker compose exec agent sh -c 'ls -la /bin/agent/collectors'
+```
+
+
diff --git a/docs/config.md b/docs/config.md
index ddb3706..e93c9ef 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -79,6 +79,44 @@ collectors:
 - `CONFIG_PATH` — путь к `config.yaml`
 - `LOG_LEVEL` — уровень логирования (`error`, `info`, `debug`)
 
+Kafka (подробности):
+- `kafka.enabled`: включает отправку в Kafka
+- `kafka.brokers`: список брокеров вида `host:port`
+- `kafka.topic`: топик для публикации
+- `kafka.client_id`: идентификатор клиента
+- `kafka.sasl_user` / `kafka.sasl_pass`: параметры SASL/PLAIN (опционально)
+- `kafka.enable_tls`: включение TLS (опционально)
+- `kafka.timeout`: таймаут отправки
+
+Пример конфигурации с Kafka и SASL/PLAIN:
+```yaml
+mode: kafka
+log_level: info
+kafka:
+  enabled: true
+  brokers: ["kafka-1:9093", "kafka-2:9093"]
+  topic: "sensus.metrics"
+  client_id: "sensusagent"
+  sasl_user: "metrics_user"
+  sasl_pass: "${KAFKA_SASL_PASS}"   # рекомендуется через переменные окружения
+  enable_tls: true
+  timeout: "5s"
+collectors:
+  system:
+    enabled: true
+    type: exec
+    key: system
+    interval: "30s"
+    timeout: "8s"
+    exec: "./collectors/system"
+    platforms: [linux]
+```
+
+Замечания по безопасности:
+- Никогда не храните пароли в открытом виде в репозитории
+- Используйте переменные окружения и секреты CI/CD
+- Минимизируйте разрешения пользователя Kafka и используйте отдельный `topic`
+
 Советы по конфигурации:
 - Для тяжелых коллекторов увеличивайте `interval` и `timeout`
 - При использовании Kafka установите `kafka.enabled: true` и корректные `brokers`/`topic`
diff --git a/docs/deploy.md b/docs/deploy.md
index 4557b1e..3acdb39 100644
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -35,6 +35,38 @@ make deploy-service
 make delete-service
 ```
 
+Прямое использование systemd юнита:
+Разместите юнит-файл по пути `/etc/systemd/system/sensusagent.service` со следующим содержимым:
+```ini
+[Unit]
+Description=SensusAgent metrics collector
+After=network.target
+
+[Service]
+Type=simple
+Environment=CONFIG_PATH=/opt/sensusagent/config.yaml
+ExecStart=/opt/sensusagent/agent --mode stdout
+Restart=on-failure
+RestartSec=3
+User=nobody
+Group=nogroup
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Команды управления:
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now sensusagent
+sudo systemctl status sensusagent
+sudo journalctl -u sensusagent -f
+```
+
+Права и директории:
+- Бинарь и конфиг по умолчанию устанавливаются в `/opt/sensusagent`
+- Убедитесь, что у пользователя сервиса есть права на чтение конфигов и исполнение бинарей
+
 Переменные Ansible:
 - `LOCAL_BIN_DIR` — локальный каталог с собранным агентом (по умолчанию `./bin/agent`)
 - `remote_dir` — удаленный каталог установки (по умолчанию `/opt/sensusagent` в плейбуках)
diff --git a/docs/faq.md b/docs/faq.md
new file mode 100644
index 0000000..78187c2
--- /dev/null
+++ b/docs/faq.md
@@ -0,0 +1,27 @@
+### FAQ / Траблшутинг
+
+Автор: Сергей Антропов, сайт: https://devops.org.ru
+
+В агенте нет вывода, пустой JSON
+- Проверьте `LOG_LEVEL` и `mode`. В режиме `stdout` вывод происходит в STDOUT, а логи — в STDERR.
+- Убедитесь, что коллекторы включены (`enabled: true`) и не превышают `timeout`.
+
+Коллектор падает по таймауту
+- Увеличьте `timeout` в конфиге
+- Проверьте доступность системных утилит (например, `smartctl`, `nvme-cli`) на целевой машине
+
+Kafka не принимает сообщения
+- Проверьте `kafka.enabled`, `brokers` и сетевую доступность
+- При необходимости включите `sasl_user`/`sasl_pass` и `enable_tls`
+
+Как посмотреть логи при запуске через systemd?
+```bash
+sudo journalctl -u sensusagent -f
+```
+
+Как отладить внешний коллектор?
+```bash
+cd bin/agent && ./collectors/<name> | jq .
+```
+
+