docs: Kafka details; systemd section; compose examples; CI/CD notes; FAQ [author: Сергей Антропов https://devops.org.ru]

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`
+

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'
+```
+
+

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`

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` в плейбуках)

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 .
+```
+
+