Перейти к содержимому
Soul Stack

Мониторинг из коробки

Наблюдаемость в Soul Stack встроена в оба исполняемых файла: Keeper и агент soul публикуют метрики и трейсы без отдельных sidecar-ов и exporter-процессов. Это руководство показывает, как забирать телеметрию, на что смотреть в первую очередь и как поставить Prometheus-экспортер на сами души средствами Soul Stack.

Справочник по конфигу телеметрии — keeper.yml → metrics/otel и soul.yml → metrics/otel; обзорная картина по эксплуатации — Операции → Мониторинг.

Два канала, две модели

Заголовок раздела «Два канала, две модели»

Телеметрия Soul Stack идёт по двум разным механизмам — и это ключевая асимметрия, которую важно усвоить сразу:

КаналМодельКто инициируетЧто несёт
Prometheus /metricspull (scrape)ваш Prometheus ходит на Soul Stackсчётчики, gauge, гистограммы
OpenTelemetrypush (OTLP)Soul Stack сам шлёт в коллекторсквозные трейсы (оператор → Keeper → агент)
  • Метрики — pull. Soul Stack слушает /metrics; Prometheus периодически скрейпит этот endpoint. У Keeper-а это порт :9090.
  • OpenTelemetry — push. У Soul Stack нет входящего OTel-порта. При включённом OTel Keeper и агент сами отправляют OTLP-трейсы в указанный вами коллектор (otel.endpoint), ничего не слушая.
flowchart LR
    subgraph pull["Pull — Prometheus ходит к нам"]
        direction LR
        P["Prometheus"] -->|scrape| K1["Keeper :9090/metrics"]
        P -->|scrape| S1["soul — metrics.listen"]
    end
    subgraph push["Push — мы шлём наружу"]
        direction LR
        K2["Keeper"] -->|OTLP| O["ваш OTel-коллектор"]
        S2["soul"] -->|OTLP| O
    end

Логи — третий канал: структурированный JSON в stdout / systemd journal, со встроенной ротацией. В записи логов есть kid/sid, id прогона и trace-id — этого достаточно, чтобы связать лог с трейсом и метрикой.

Метрики: scrape /metrics

Заголовок раздела «Метрики: scrape /metrics»

Keeper

Заголовок раздела «Keeper»

Keeper обслуживает /metrics на отдельном listener-е (порт :9090 в примерах) — без auth-цепочки Operator API. Проверить вручную:

Окно терминала
curl -s http://keeper.example.com:9090/metrics | head -40

Скрейп-конфиг Prometheus:

prometheus.yml
scrape_configs:
  - job_name: keeper
    static_configs:
      - targets:
          - keeper.example.com:9090

Метрики Keeper-а имеют префикс keeper_.

Агент soul

Заголовок раздела «Агент soul»

Агент тоже публикует /metrics (префикс soul_), но по умолчанию слушает loopback (127.0.0.1) — наружу не торчит. Это намеренно: managed-хост не должен открывать лишних входящих портов.

Чтобы скрейпить агентов извне, в soul.yml сменить bind на внешний интерфейс и включить Basic-auth:

soul.yml
metrics:
  listen: "0.0.0.0:9091"
  auth:
    basic:
      username: prometheus
      password_file: /etc/soul/metrics-password   # mode 0400

Без этого агент остаётся на loopback — корректно для большинства инсталляций, где метрики хоста собирает локальный node-агент. Детали — soul.yml → metrics.

На что смотреть в первую очередь

Заголовок раздела «На что смотреть в первую очередь»

Доменные идентификаторы (id прогона, sid, имя сценария) живут в трейсах, а не в метках метрик — сознательно, чтобы не раздувать кардинальность Prometheus. Поэтому метрики отвечают на «что-то не так?», а конкретного виновника ищут по трейсам и логам.

СигналМетрика (ориентир)О чём говорит
Доступность инстансаup{job="keeper"}инстанс не отвечает — смотреть логи
Подключённые агентыkeeper_grpc_streams_activeпадение ниже ожидаемого — часть душ отвалилась
Фоновая чисткаgauge лидерства Reaper-а (sum по кластеру = 1)ноль — чистка БД остановлена, таблицы растут; >1 — аномалия координации
Планировщик расписанийgauge лидерства планировщика (sum = 1, если включён)ноль при включённом — регулярные запуски не порождаются
Доля провальных прогоновrate провальных / всех scenario-прогоноврост выше нормы — investigate сценарий или хосты
Латентность Vaultгистограмма чтения Vaultрост — Vault отвечает медленно, операции замедляются

Трейсы: OpenTelemetry push

Заголовок раздела «Трейсы: OpenTelemetry push»

OTel включается в конфиге; при otel.enabled: true исполняемый файл сам пушит OTLP по gRPC в otel.endpoint:

# keeper.yml (симметрично в soul.yml)
otel:
  enabled: true
  endpoint: "otel-collector.example.com:4317"

Трейсы — сквозные: одна операция оператора (например, прогон сценария) прослеживается через Keeper до конкретного агента и обратно. Именно по трейсам (по correlation-id и id прогона) ищут, где замедлилось или упало — метрики дают агрегат, трейс даёт конкретный путь.

Подробности по ключам — keeper.yml → otel и soul.yml → otel.

Поставить экспортер на души средствами Soul Stack

Заголовок раздела «Поставить экспортер на души средствами Soul Stack»

Метрики самого Soul Stack — это одно; метрики хостов (CPU, память, диск, сеть) собирает Prometheus-экспортер на каждом хосте. Раскатать его — обычная задача для Soul Stack: тот же сценарий, что и любой другой сервис.

Экспортер оформляется как отдельный сервис в git — Destiny, который скачивает релиз (с проверкой контрольной суммы), ставит исполняемый файл под выделенным системным пользователем, разворачивает systemd-unit и запускает его, — и применяется на души ровно как любой другой сервис (Первый сервис на душах, Оркестрация). Всё на штатных core-модулях: core.url.fetched (с checksum:) → core.archive.extracted → core.cmd.shell (install) → core.file.rendered (unit) → core.service.running; архитектуру хоста берите из soulprint.self.os.arch, чтобы один прогон покрывал смешанные amd64/arm64-души.

Готового публичного сервиса-экспортера пока нет — соберите свой по образцу первого сервиса на душах либо переложите существующий node_exporter-плейбук на эти модули. Результат — :9100/metrics на каждом хосте, который скрейпит ваш Prometheus рядом с метриками самого Soul Stack.

Что дальше

Заголовок раздела «Что дальше»